Agent Memory System

Hybrid architecture for persistent agent memory that learns from experience.

Architecture

• PostgreSQL: Structured task logs, execution history, agent performance metrics
• ChromaDB: Semantic search over task embeddings for similarity matching
• Python API: Interface for storing tasks and querying similar executions

Stack

• PostgreSQL 16
• ChromaDB (latest)
• Python 3.11+
• Docker Compose for local deployment

Features

• ✅ Store task execution history with outcomes
• ✅ Semantic similarity search for related tasks
• ✅ Agent performance tracking and routing confidence
• ✅ Context injection with reference to past solutions
• ✅ Compound learning (gets smarter with each execution)

Quick Start

# Start the stack
docker-compose up -d

# Install Python dependencies
pip install -r requirements.txt

# Run example
python examples/basic_workflow.py

Usage

from agent_memory import MemorySystem

memory = MemorySystem()

# Store a task execution
memory.store_task(
    task_id="task_001",
    description="Add dark mode toggle to settings",
    agent="frontend-developer",
    status="success",
    duration_min=12,
    solution="Used React context + CSS variables",
    techniques=["react-context", "css-variables"]
)

# Find similar tasks
similar = memory.find_similar(
    query="Implement theme switcher",
    n_results=5,
    filters={"success": True}
)

# Get agent stats
stats = memory.get_agent_stats("frontend-developer", task_type="ui-toggle")
print(f"Success rate: {stats['success_rate']}")
print(f"Avg duration: {stats['avg_duration']} min")

Schema

See docs/schema.md for full database schema and examples.

Architecture Details

See the design document for the full explanation of how the hybrid system works.

License

MIT

LangChain/LangGraph Integration (Optional)

The system includes optional LangChain integration for those using the LangChain ecosystem.

Install

pip install -r requirements-langchain.txt

Usage

LangChain Memory:

from agent_memory import MemorySystem
from agent_memory.langchain_adapter import AgentMemoryRetriever

memory = MemorySystem()
langchain_memory = AgentMemoryRetriever(memory)

# Use in chains
from langchain.chains import ConversationChain

chain = ConversationChain(
    llm=llm,
    memory=langchain_memory
)

LangGraph Workflow:

# See examples/langchain/langgraph_workflow.py
# Demonstrates task routing with memory-backed agent selection

Core system remains dependency-free — LangChain is completely optional.