agent-reminiscence 0.1.3

Hierarchical memory management for AI agents with vector search and graph relationships

Agent Mem

A standalone Python package for hierarchical memory management in AI agents. Provides a stateless interface to manage active, short-term, and long-term memories with vector search, graph relationships, and intelligent consolidation.

🚀 Quick Links

• 📚 Documentation Index: See docs/INDEX.md for all documentation
• 🎯 Getting Started: See docs/GETTING_STARTED.md for setup and testing
• ⚡ Quick Start: See docs/QUICKSTART.md for 5-minute setup
• 🐛 Bug Fixes: See docs/BUG_FIXES.md for resolved issues
• 🏗️ Architecture: See docs/ARCHITECTURE.md for system design
• 👨‍💻 Development: See docs/DEVELOPMENT.md for implementation guide
• 📊 Progress: See docs/IMPLEMENTATION_STATUS.md for current status
• 🤖 Phase 4: See docs/PHASE4_COMPLETE.md for AI agent integration

✅ Current Status

Overall Progress: 89% complete (98/110 major tasks completed)

Completed Phases:

• ✅ Phase 1: Core infrastructure (PostgreSQL + Neo4j, embedding service)
• ✅ Phase 2: Memory tiers (Active, Shortterm, Longterm repositories)
• ✅ Phase 3: Memory Manager (consolidation, promotion, retrieval)
• ✅ Phase 4: AI Agents (ER Extractor, Memory Retrieve, Memory Update)
• ✅ Phase 5: Testing (27 test suites - needs rewrite to match implementation)
• ✅ Phase 9: Streamlit UI (100% - Web UI fully functional)
• ✅ Phase 10: MCP Server (100% - Claude Desktop integration ready)

In Progress:

• 📖 Phase 6: Examples and demonstrations (20% complete)
• 📚 Phase 7: Complete API documentation (50% complete)
• 🚀 Phase 8: Production deployment (not started)

See docs/IMPLEMENTATION_STATUS.md for detailed progress

🎨 Streamlit Web UI

NEW: AgentMem now includes a web-based UI for managing memories without writing code!

Features

• 📚 Browse Templates - Explore 60+ pre-built BMAD templates
• ➕ Create Memories - Create memories using templates or custom YAML
• 📋 View Memories - Browse all memories for an agent
• ✏️ Update Sections - Edit memory sections with live Markdown preview
• 🗑️ Delete Memories - Safely delete with type-to-confirm protection

Starting the UI

cd streamlit_app
streamlit run app.py

The UI will open at http://localhost:8501

User Guide

See docs/STREAMLIT_UI_USER_GUIDE.md for complete usage instructions.

---

🔌 MCP Server for Claude Desktop

NEW: AgentMem now includes a Model Context Protocol (MCP) server for integration with Claude Desktop and other MCP clients!

Features

• 🔍 get_active_memories - Retrieve all active memories for an agent
• ➕ create_active_memory - Create new active memory with template
• 📝 update_memory_sections - Batch upsert multiple sections (insert/update/replace)
• 🗑️ delete_active_memory - Delete an active memory
• 🔎 search_memories - Search across memory tiers with AI-synthesized responses

Quick Start

# Run the MCP server (recommended: using uv)
uv run agent_reminiscence_mcp\run.py

# Alternative: using Python directly
py agent_reminiscence_mcp\run.py

# Add sample data for testing
uv run agent_reminiscence_mcp\tests\add_sample_data.py

# Test with Python client
uv run agent_reminiscence_mcp\tests\test_mcp_client.py

Claude Desktop Integration

Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "agent-reminiscence": {
      "command": "uv",
      "args": [
        "run",
        "path_to_agent_reminiscence_mcp\\run.py"
      ],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "agent_reminiscence",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "neo4jpassword",
        "OLLAMA_BASE_URL": "http://localhost:11434"
      }
    }
  }
}

Important:

• Use uv command for better dependency management
• Use absolute path (adjust to your installation directory)
• Ensure environment variables match your .env file
• Double backslashes required in JSON on Windows

Documentation

• MCP Server README - Complete MCP server documentation
• Getting Started with MCP - Quick start guide
• MCP Server Status - Implementation status
• Implementation Details - Technical details

---

Key Features

• Stateless Design: One AgentMem instance can serve multiple agents/workers
• Template-Driven Memory: Active memories use YAML templates with structured sections
• Section-Level Tracking: Each section tracks its own update_count for consolidation
• Three-Tier Memory: Active (template+sections) → Shortterm (chunks+entities) → Longterm (temporal)
• Simple API: Just 4 methods to manage all your agent's memories
• Vector Search: Semantic search using embeddings via Ollama
• Graph Relationships: Entity and relationship tracking with Neo4j
• Smart Consolidation: Automatic section-level consolidation with conflict resolution
• Generic ID Support: Use any external ID (UUID, string, int) for your agents

Quick Start

Installation

Linux/Mac:

cd libs/agent_reminiscence
pip install -e .

Windows:

cd libs\agent_reminiscence
py -m pip install -e .

Or add to your project's requirements:

echo "agent-reminiscence @ file:///${PWD}/libs/agent_reminiscence" >> requirements.txt

Prerequisites

Using Docker Compose (Recommended):

The easiest way is to use the provided Docker Compose configuration:

# Start all services (PostgreSQL, Neo4j, Ollama)
docker compose up -d

# Check services are running
docker compose ps

Manual Setup:

1. PostgreSQL with extensions:

   • pgvector for vector storage
   • pg_tokenizer for text tokenization
   • vchord_bm25 for BM25 search

2. Neo4j for graph storage

3. Ollama for embeddings:

   ollama pull nomic-embed-text
   

Configuration

AgentMem supports three configuration methods:

Pattern 1: Direct Python (Recommended for PyPI users)

from agent_reminiscence import AgentMem, Config

config = Config(
    postgres_host="localhost",
    postgres_password="secure_password",
    neo4j_uri="bolt://localhost:7687",
    neo4j_password="neo4j_password",
    ollama_base_url="http://localhost:11434"
)

agent_reminiscence = AgentMem(config=config)

Pattern 2: Environment Variables (Recommended for Docker/K8s)

export POSTGRES_HOST=postgres
export POSTGRES_PASSWORD=secure_pass
export NEO4J_URI=bolt://neo4j:7687
export NEO4J_PASSWORD=neo4j_pass
export OLLAMA_BASE_URL=http://ollama:11434
python your_app.py

from agent_reminiscence import AgentMem

agent_reminiscence = AgentMem()  # Uses environment variables

Pattern 3: .env File (Convenient for local development)

Create a .env file:

# PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DB=agent_reminiscence

# Neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password
NEO4J_DATABASE=neo4j

# Ollama
OLLAMA_BASE_URL=http://localhost:11434

# Model Configuration
EMBEDDING_MODEL=nomic-embed-text
VECTOR_DIMENSION=768

# Agent Models (Optional - defaults to Gemini)
MEMORY_UPDATE_AGENT_MODEL=google:gemini-2.0-flash
MEMORIZER_AGENT_MODEL=google:gemini-2.0-flash
MEMORY_RETRIEVE_AGENT_MODEL=google:gemini-2.0-flash

# Automatically loaded if python-dotenv is available
from agent_reminiscence import AgentMem

agent_reminiscence = AgentMem()  # Uses .env file

Note: python-dotenv is optional. Install with pip install agent-reminiscence[dev] for .env file support.

Basic Usage

from agent_reminiscence import AgentMem
import asyncio

# Template defining memory structure
TASK_TEMPLATE = """
template:
  id: "task_memory_v1"
  name: "Task Memory"
sections:
  - id: "current_task"
    title: "Current Task"
  - id: "progress"
    title: "Progress"
"""

async def main():
    # Initialize STATELESS memory manager (serves multiple agents)
    agent_reminiscence = AgentMem()
    
    # Initialize database connections
    await agent_reminiscence.initialize()
    
    try:
        # 1. Create an active memory with template
        memory = await agent_reminiscence.create_active_memory(
            external_id="agent-123",  # Pass agent ID to method
            title="Build Dashboard",
            template_content=TASK_TEMPLATE,  # Can be YAML string or dict
            initial_sections={
                "current_task": {
                    "content": "Implement real-time analytics",
                    "update_count": 0,
                    "awake_update_count": 0,
                    "last_updated": None
                },
                "progress": {
                    "content": "- Designed UI\n- Set up project",
                    "update_count": 0,
                    "awake_update_count": 0,
                    "last_updated": None
                }
            },
            metadata={"priority": "high"}
        )
        print(f"Created memory: {memory.id}")
        
        # 2. Get all active memories for agent
        all_memories = await agent_reminiscence.get_active_memories(
            external_id="agent-123"
        )
        print(f"Total memories: {len(all_memories)}")
        
        # 3. Update multiple sections with upsert (batch operation)
        await agent_reminiscence.update_active_memory_sections(
            external_id="agent-123",
            memory_id=memory.id,
            sections=[
                {
                    "section_id": "progress",
                    "new_content": "- Designed UI\n- Set up project\n- Implemented analytics",
                    "action": "replace"  # Replace entire content
                },
                {
                    "section_id": "blockers",  # New section (upsert)
                    "new_content": "# Blockers\n- None currently",
                    "action": "replace"
                }
            ]
        )
            new_content="- Designed UI\n- Set up project\n- Implemented charts"
        )
        
        # 4. Retrieve memories (searches across all tiers)
        results = await agent_reminiscence.retrieve_memories(
            external_id="agent-123",
            query="What is the current progress on the dashboard?",
            limit=10,
            synthesis=True  # Request AI summary of findings
        )
        
        # Access results
        print(f"Mode: {results.mode}")  # "pointer" or "synthesis"
        print(f"Found {len(results.chunks)} chunks, {len(results.entities)} entities")
        if results.synthesis:
            print(f"AI Summary: {results.synthesis}")
        
    finally:
        # Clean up connections
        await agent_reminiscence.close()

if __name__ == "__main__":
    asyncio.run(main())

Architecture

agent_reminiscence/
├── __init__.py              # Public API exports
├── core.py                  # AgentMem main class (STATELESS)
├── config/
│   ├── __init__.py
│   └── settings.py          # Configuration management
├── database/
│   ├── __init__.py
│   ├── postgres_manager.py  # PostgreSQL connection pool
│   ├── neo4j_manager.py     # Neo4j connection manager
│   ├── repositories/
│   │   ├── __init__.py
│   │   ├── active_memory.py      # Template + section CRUD
│   │   ├── shortterm_memory.py   # Shortterm memory CRUD
│   │   └── longterm_memory.py    # Longterm memory CRUD
│   └── models.py            # Pydantic models for data
├── services/
│   ├── __init__.py
│   ├── embedding.py         # Ollama embedding service
│   └── memory_manager.py    # Core memory operations (stateless)
├── agents/
│   ├── __init__.py
│   ├── memory_updater.py    # Memory Update Agent
│   ├── memorizer.py         # Memory Consolidation Agent
│   └── memory_retriever.py  # Memory Retrieve Agent
├── utils/
│   ├── __init__.py
│   └── helpers.py           # Utility functions
└── sql/
    ├── schema.sql           # PostgreSQL schema
    └── migrations/          # Future migrations

API Reference

AgentMem

The main class for memory management (STATELESS - serves multiple agents).

__init__(config: Optional[Config] = None)

Initialize stateless memory manager.

Parameters:

• config: Optional configuration object (uses environment variables by default)

async initialize() -> None

Initialize database connections and ensure schema exists.

async create_active_memory(external_id: str | UUID | int, title: str, template_content: str | dict, initial_sections: Optional[dict] = None, metadata: Optional[dict] = None) -> ActiveMemory

Create a new active memory with template-driven structure.

Parameters:

• external_id: Unique identifier for the agent (UUID, string, or int)
• title: Memory title
• template_content: Template defining section structure. Can be:
  • Dict (JSON): {"template": {...}, "sections": [{"id": "...", "description": "..."}]}
  • Str (YAML): Parsed to dict automatically (backward compatible)
• initial_sections: Optional initial sections that override template defaults
  • Format: {"section_id": {"content": "...", "update_count": 0, "awake_update_count": 0, "last_updated": None}}
• metadata: Optional metadata dictionary

Returns: Created ActiveMemory object with sections

Section Structure: Each section contains:

• content: Markdown content
• update_count: Updates since last consolidation (resets to 0 after consolidation)
• awake_update_count: Total updates (never resets, for future sleep/wake features)
• last_updated: ISO timestamp of last update

async get_active_memories(external_id: str | UUID | int) -> List[ActiveMemory]

Get all active memories for a specific agent.

Parameters:

• external_id: Unique identifier for the agent

Returns: List of ActiveMemory objects

async update_active_memory_section(external_id: str | UUID | int, memory_id: int, section_id: str, new_content: str) -> ActiveMemory

Update a specific section in an active memory.

Automatically increments the section's update_count and awake_update_count, and triggers consolidation when threshold is reached.

Parameters:

• external_id: Unique identifier for the agent
• memory_id: ID of memory to update
• section_id: Section ID to update (defined in template)
• new_content: New content for the section

Returns: Updated ActiveMemory object

async update_active_memory_sections(external_id: str | UUID | int, memory_id: int, sections: List[dict]) -> ActiveMemory

Upsert multiple sections in an active memory (batch operation).

Supports creating new sections, updating existing ones, content replacement with pattern matching, and content insertion/appending.

Parameters:

• external_id: Unique identifier for the agent
• memory_id: ID of memory to update
• sections: List of section updates with structure:

  [
    {
      "section_id": "progress",
      "old_content": "# Old",  # Optional: pattern to find
      "new_content": "# New",
      "action": "replace"  # "replace" or "insert"
    }
  ]
  

Action Behaviors:

• replace + no old_content: Replace entire section
• replace + old_content: Replace that substring
• insert + no old_content: Append at end
• insert + old_content: Insert after pattern

Returns: Updated ActiveMemory object

async retrieve_memories(external_id: str | UUID | int, query: str, limit: int = 10, synthesis: bool = False) -> RetrievalResult

Search and retrieve relevant memories for a specific agent across all tiers.

Parameters:

• external_id: Unique identifier for the agent
• query: Natural language search query describing the context and what information is needed
• limit: Maximum results per tier (default: 10)
• synthesis: Force AI to generate a synthesized summary of results (default: False, AI decides)

Returns: RetrievalResult with matched chunks, entities, relationships, and optional AI synthesis

async close() -> None

Close all database connections.

Memory Tiers

Active Memory

• Purpose: Template-driven working memory with sections
• Storage: PostgreSQL with JSONB sections
• Structure: JSON/YAML template + sections
  • Each section: {content, update_count, awake_update_count, last_updated}
• Lifetime: Short (hours to days)
• Updates: Frequent (per-section tracking with dual counters)
• Use Case: Current task context, ongoing work, structured progress tracking
• Consolidation: Section-level triggers based on update_count threshold

Shortterm Memory

• Purpose: Searchable recent knowledge
• Storage: PostgreSQL (vectors + BM25) + Neo4j (entities/relationships)
• Lifetime: Medium (days to weeks)
• Updates: Occasional (from active memory consolidation)
• Use Case: Recent implementations, conversations, research findings

Longterm Memory

• Purpose: Consolidated knowledge base
• Storage: PostgreSQL (vectors + BM25) + Neo4j (entities/relationships)
• Lifetime: Long (persistent)
• Updates: Rare (promoted from shortterm with intelligent merging)
• Use Case: Core knowledge, patterns, historical decisions
• Promotion: Automatic with type merging, confidence recalculation, and state history tracking

Advanced Usage

Custom Configuration

from agent_reminiscence import AgentMem, Config

config = Config(
    postgres_host="custom-host",
    postgres_port=5433,
    embedding_model="custom-model",
    vector_dimension=1024,
)

agent_reminiscence = AgentMem(external_id="agent-456", config=config)

Automatic Consolidation

Memory consolidation happens automatically based on update thresholds. You can also trigger it manually:

# This is done internally, but exposed for advanced use cases
from agent_reminiscence.services import MemoryManager

manager = MemoryManager(external_id="agent-123")
await manager.consolidate_to_shortterm(active_memory_id=1)
await manager.promote_to_longterm(shortterm_memory_id=5)

Intelligent Promotion to Longterm

When shortterm memories are promoted to longterm, the system performs intelligent merging:

Entity Merging:

• Matches entities by name (case-insensitive)
• Merges types from both memories (union operation)
• Recalculates confidence using weighted average (favors higher confidence)
• Tracks complete state history in metadata

Relationship Merging:

• Matches relationships by source and target entity names
• Merges types from both memories (union operation)
• Recalculates confidence and strength using weighted averages
• Tracks complete state history in metadata

State History Example:

# Each entity/relationship tracks its evolution in metadata.state_history:
{
    "state_history": [
        {
            "timestamp": "2025-10-05T10:30:00Z",
            "source": "shortterm_promotion",
            "old_types": ["Person", "Developer"],
            "new_types": ["Person", "Developer", "Team Lead"],
            "old_confidence": 0.75,
            "new_confidence": 0.82
        }
    ]
}

This ensures no information is lost during promotion and provides a complete audit trail.

Working with Entities and Relationships

# Entities and relationships are automatically extracted during consolidation
# You can query them through the retrieval results

result = await agent_reminiscence.retrieve_memories("authentication system")

# Access entities
for entity in result.entities:
    print(f"Entity: {entity.name} (type: {entity.type})")

# Access relationships
for rel in result.relationships:
    print(f"Relationship: {rel.from_entity} -> {rel.type} -> {rel.to_entity}")

Development

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run with coverage
pytest --cov=agent_reminiscence tests/

Building Documentation

cd docs/
mkdocs serve  # View locally
mkdocs build  # Build static site

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Support

• Documentation: Full Documentation
• Issues: GitHub Issues
• Discussions: GitHub Discussions