Skip to content

README.md

Latest commit

 

History

History
322 lines (252 loc) · 8.96 KB

README.md

File metadata and controls

322 lines (252 loc) · 8.96 KB

AgentMemory 🧠

Python License: MIT Status

Language Versions: English | 한국어 | Deutsch | 日本語 | العربية

AgentMemory is an advanced memory management framework for AI agents, providing persistent, hierarchical, and semantic memory capabilities. It addresses the critical gap in current agentic AI development: robust memory and context management across agent sessions.

🚀 Key Features

🎯 Multiple Memory Types

  • Short-Term Memory: FIFO buffer with TTL for immediate context
  • Long-Term Memory: Importance-based retention for valuable information
  • Episodic Memory: Temporal organization of event sequences
  • Semantic Memory: Concept-based knowledge with relationships
  • Procedural Memory: Skills and how-to knowledge with execution tracking

🔍 Advanced Retrieval

  • Semantic Search: Vector similarity search using embeddings
  • Filtered Queries: Retrieve by type, tags, importance, or custom metadata
  • Relationship Navigation: Follow memory associations and relations
  • Time-Decay Scoring: Automatic relevance calculation with decay

💾 Persistence & Storage

  • Multiple Backends: In-memory, vector stores (NumPy/FAISS)
  • Save/Load: JSON serialization for memory persistence
  • Batch Operations: Efficient bulk add/delete operations

🔄 Memory Management

  • Auto-Consolidation: Automatic promotion from short-term to long-term
  • Importance Scoring: Configurable importance thresholds
  • Memory Associations: Create relationships between memories
  • Statistics Tracking: Monitor memory usage and patterns

📦 Installation

pip install agentmemory

For development:

git clone https://github.com/hanishkeloth/agentmemory.git
cd agentmemory
pip install -e ".[dev]"

🎓 Quick Start

from agentmemory import MemoryManager

# Initialize memory manager
memory = MemoryManager()

# Add memories
memory.add(
    "User prefers Python for data science",
    memory_type="long_term",
    importance=0.9,
    tags=["preference", "python"]
)

# Retrieve relevant memories
memories = memory.retrieve(
    query="What programming language to use?",
    limit=5
)

# Create associations
memory.create_association(memory1_id, memory2_id, "related_to")

# Save for persistence
memory.save("agent_memories.json")

💡 Use Cases

🤖 Conversational AI Agents

class ChatAgent:
    def __init__(self):
        self.memory = MemoryManager()
    
    def process(self, user_input):
        # Store conversation
        self.memory.add(
            user_input,
            memory_type="short_term",
            session_id=self.session_id
        )
        
        # Retrieve context
        context = self.memory.retrieve(user_input, limit=5)
        
        # Generate response with context
        response = self.generate_response(user_input, context)
        return response

📚 Knowledge Management

# Store facts with concepts
memory.add(
    "Python was created in 1991 by Guido van Rossum",
    memory_type="semantic",
    concepts=["python", "history", "programming"],
    importance=0.8
)

# Query by concepts
python_facts = memory.retrieve(concepts=["python"], limit=10)

🔧 Skill Learning

# Store procedures
memory.add(
    {"procedure": "Deploy to AWS", "steps": [...]},
    memory_type="procedural",
    procedure_name="aws_deployment",
    skill_level=0.7
)

# Track execution success
memory.update_execution(procedure_id, success=True)

🏗️ Architecture

AgentMemory/
├── core/
│   ├── memory_manager.py    # Central orchestrator
│   ├── memory_types.py      # Memory type implementations
│   └── memory_entry.py      # Memory data structures
├── stores/
│   ├── base.py             # Abstract store interface
│   └── vector.py           # Vector similarity stores
├── retrievers/
│   ├── base.py             # Abstract retriever interface
│   └── semantic.py         # Semantic search implementation
└── utils/
    └── embeddings.py       # Embedding utilities

🔬 Advanced Features

Memory Consolidation

# Automatic consolidation from short-term to long-term
manager = MemoryManager(consolidation_threshold=10)

# Manual consolidation
stats = manager.consolidate_memories()
print(f"Promoted to long-term: {stats['promoted_to_long_term']}")

Custom Metadata

memory.add(
    "Important event",
    memory_type="episodic",
    custom_metadata={
        "location": "San Francisco",
        "participants": ["Alice", "Bob"],
        "outcome": "successful"
    }
)

Vector Search with Embeddings

from agentmemory.utils.embeddings import EmbeddingManager

embedder = EmbeddingManager()
embedding = embedder.encode_single("Machine learning concept")

memory.add(
    "Neural networks are inspired by biological neurons",
    memory_type="semantic",
    embedding=embedding
)

🤝 Integration with Popular Frameworks

LangChain

from langchain.memory import ConversationBufferMemory
from agentmemory import MemoryManager

class AgentMemoryWrapper(ConversationBufferMemory):
    def __init__(self):
        super().__init__()
        self.agent_memory = MemoryManager()
    
    def save_context(self, inputs, outputs):
        super().save_context(inputs, outputs)
        self.agent_memory.add(
            {"input": inputs, "output": outputs},
            memory_type="episodic"
        )

AutoGen

from autogen import AssistantAgent
from agentmemory import MemoryManager

class MemoryAgent(AssistantAgent):
    def __init__(self, name, **kwargs):
        super().__init__(name, **kwargs)
        self.memory = MemoryManager()
    
    def receive(self, message, sender):
        # Store message in memory
        self.memory.add(
            message,
            memory_type="short_term",
            agent_id=sender.name
        )
        return super().receive(message, sender)

📊 Performance Considerations

  • Embedding Dimension: Default 384 (all-MiniLM-L6-v2), adjustable for performance
  • Capacity Limits: Configurable per memory type to manage resource usage
  • Batch Operations: Use batch methods for bulk operations
  • Vector Store Choice: NumPy for small-scale, FAISS for production

🛠️ Development

Run tests:

pytest tests/

Format code:

black agentmemory/
ruff check agentmemory/

Type checking:

mypy agentmemory/

📈 Benchmarks

Operation 1K Memories 10K Memories 100K Memories
Add 0.8ms 0.9ms 1.1ms
Retrieve 2.3ms 8.7ms 45ms
Search 3.1ms 12ms 89ms

Tested on MacBook Pro M1, 16GB RAM

🗺️ Roadmap

  • Distributed memory stores (Redis, PostgreSQL)
  • Graph-based memory relationships
  • Memory compression and summarization
  • Multi-agent memory sharing
  • Memory versioning and rollback
  • Advanced consolidation strategies
  • Memory attention mechanisms
  • Integration with more frameworks

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Hanish Keloth

🙏 Acknowledgments

  • Inspired by cognitive architectures and human memory systems
  • Built to address gaps identified in current agentic AI frameworks
  • Thanks to the open-source AI community for continuous innovation

📚 Citations

If you use AgentMemory in your research or projects, please cite:

@software{agentmemory2025,
  author = {Keloth, Hanish},
  title = {AgentMemory: Advanced Memory Management for AI Agents},
  year = {2025},
  url = {https://github.com/hanishkeloth/agentmemory}
}

🔗 Links

Note: This project is in beta. APIs may change in future versions. Please report any issues or suggestions!