A-MEM: Agentic Memory System

An agentic memory system for LLM agents based on the Zettelkasten principle.

Based on: "A-Mem: Agentic Memory for LLM Agents"
by Wujiang Xu, Zujie Liang, Kai Mei, Hang Gao, Juntao Tan, Yongfeng Zhang
Rutgers University, Independent Researcher, AIOS Foundation

🚀 Features

Core Features

• ✅ Note Construction: Automatic extraction of keywords, tags, and contextual summary
• ✅ Link Generation: Automatic linking of similar memories
• ✅ Memory Evolution: Dynamic updating of existing memories
• ✅ Semantic Retrieval: Intelligent search with graph traversal
• ✅ Multi-Provider Support: Ollama (local) or OpenRouter (cloud)
• ✅ Environment Variables: Configuration via .env file
• ✅ Graph Backend Selection: Choose between NetworkX (default), RustworkX (3x-100x faster), or FalkorDB (experimental, not fully tested)
• ✅ Parameter Validation: Automatic validation of all MCP tool parameters
• ✅ Safe Graph Wrapper: Edge case handling and data sanitization for robust operations

Advanced Features (New)

• ✅ Type Classification: Automatic classification of notes into 6 types (rule, procedure, concept, tool, reference, integration)
• ✅ Priority Scoring: On-the-fly priority calculation based on type, age, usage, and edge count for better search rankings
• ✅ Event Logging: Append-only JSONL event log for all critical operations (NOTE_CREATED, RELATION_CREATED, MEMORY_EVOLVED)
• ✅ Memory Enzymes: Autonomous background processes for graph maintenance
  • Link Pruner: Removes old/weak edges automatically
  • Relation Suggester: Finds new semantic connections between notes
  • Dead-End Node Auto-Linker: Automatically creates out-connections for dead-end nodes with intelligent filtering
  • Summary Digester: Compresses overcrowded nodes with many children
• ✅ Automatic Scheduler: Runs memory enzymes every hour in the background
• ✅ Metadata Field: Experimental fields support without schema changes
• ✅ Researcher Agent: Deep web research for low-confidence queries (JIT context optimization)
  • Automatic triggering when retrieval confidence < threshold
  • Manual research via research_and_store MCP tool
  • Hybrid approach: MCP tools (if available) or HTTP-based fallbacks (Google Search API, DuckDuckGo, Jina Reader)
• ✅ Local Jina Reader: Support for local Docker-based Jina Reader instance (fallback to cloud API)
• ✅ Unstructured PDF Extraction: Automatic PDF extraction using Unstructured (library or API)

🔄 Relationship to Original Implementation

This implementation was developed independently based on the research paper "A-Mem: Agentic Memory for LLM Agents". The original authors' production-ready system (A-mem-sys) was discovered after this implementation was completed.

Key Differences:

This implementation focuses on MCP Server integration for IDE environments (Cursor, VSCode), providing:

• Direct IDE integration via MCP protocol
• Explicit graph-based memory linking using NetworkX (DiGraph) with typed edges, reasoning, and weights
• File import with automatic chunking
• Memory reset and management tools
• Modern TUI benchmarking tool for Ollama model speed testing

The original A-mem-sys repository provides a pip-installable Python library with:

• Multiple LLM backend support (OpenAI, Ollama, OpenRouter, SGLang)
• Library-based integration for Python applications
• Comprehensive API for programmatic usage
• Implicit linking via ChromaDB embeddings (no explicit graph structure)

Technical Architecture Difference:

• This implementation: Dual-storage architecture

  • ChromaDB for vector similarity search
  • Graph Backend Selection: NetworkX (default), RustworkX (3x-100x faster), or FalkorDB (experimental, not fully tested)
  • Explicit typed relationships (with relation_type, reasoning, weight)
  • Graph traversal for finding directly connected memories
  • Enables complex queries like "find all memories related to X through type Y"
  • Safe Graph Wrapper: Automatic edge case handling and data sanitization

• Original implementation: Single-storage architecture

  • ChromaDB as primary storage
  • Implicit linking through embedding similarity
  • Simpler architecture, less overhead

Both implementations are valid approaches to the same research paper, serving different use cases and integration scenarios.

🆕 New Features Overview

Type Classification

Every note is automatically classified into one of 6 types:

• rule: Imperative instructions ("Never X", "Always Y")
• procedure: Numbered steps or sequential instructions
• concept: Explanations of concepts, no commands
• tool: Describes functions, APIs, or utilities
• reference: Tables, comparison lists, cheatsheets
• integration: Describes connections between systems

Priority Scoring

Search results are ranked using on-the-fly priority calculation:

• Type Weight: Rules and procedures have higher priority
• Age Factor: Newer notes have higher priority
• Usage Count: Frequently accessed notes get boosted
• Edge Count: Well-connected notes are prioritized

Event Logging

All critical operations are logged to data/events.jsonl:

• NOTE_CREATED: When a new note is created
• RELATION_CREATED: When two notes are linked
• MEMORY_EVOLVED: When an existing note is updated
• LINKS_PRUNED: When old/weak links are removed
• RELATION_PRUNED: When a specific relation is pruned (with reason)
• NODE_PRUNED: When a zombie node is removed
• DUPLICATES_MERGED: When duplicate notes are merged
• SELF_LOOPS_REMOVED: When self-loops are removed
• ISOLATED_NODES_FOUND: When isolated nodes are detected
• ISOLATED_NODES_LINKED: When isolated nodes are automatically linked
• KEYWORDS_NORMALIZED: When keywords are normalized
• QUALITY_SCORES_CALCULATED: When quality scores are calculated
• NOTES_VALIDATED: When notes are validated
• TYPES_VALIDATED: When note types are validated and corrected
• NOTES_ARCHIVED: When old notes are archived (temporal cleanup)
• NOTES_DELETED: When old notes are deleted (temporal cleanup)
• GRAPH_HEALTH_CALCULATED: When graph health score is calculated
• DEAD_END_NODES_FOUND: When dead-end nodes are detected
• DEAD_END_NODES_AUTO_LINKED: When dead-end nodes are automatically linked with out-connections
• LOW_QUALITY_NOTES_REMOVED: When low-quality notes are removed
• CORRUPTED_NODES_REPAIRED: When corrupted nodes are repaired
• RELATIONS_SUGGESTED: When new connections are found
• ENZYME_SCHEDULER_RUN: When automatic maintenance runs

Memory Enzymes

Autonomous background processes that maintain graph health:

• Link Pruner: Removes edges older than 90 days or with weight < 0.3, and orphaned edges to missing/zombie nodes
• Zombie Node Remover: Automatically removes nodes without content (empty nodes)
• Duplicate Merger: Finds and merges duplicate notes (exact matches + semantic duplicates via embeddings)
• Edge Validator: Validates and fixes edges (adds missing reasoning, standardizes types, removes weak edges)
• Self-Loop Remover: Removes self-referential edges (nodes linking to themselves)
• Isolated Node Finder: Identifies nodes without any connections
• Isolated Node Linker: Automatically links isolated nodes to similar notes (similarity threshold: 0.70)
• Keyword Normalizer: Normalizes and cleans keywords (removes duplicates, corrects typos, limits to max 7 keywords)
• Quality Score Calculator: Calculates quality scores for notes (based on content, metadata, connections)
• Note Validator: Validates notes and corrects missing/invalid fields (summary, keywords, tags)
• Type Validator: Validates and corrects invalid note types using LLM-based classification
• Temporal Note Cleanup: Archives or deletes notes older than specified age (default: 365 days)
• Graph Health Score Calculator: Calculates overall graph health score (0.0-1.0) based on average note quality, connectivity, edge quality, and completeness
• Dead-End Node Detector: Identifies nodes with incoming but no outgoing edges (dead ends in knowledge flow)
• Dead-End Node Auto-Linker: Automatically creates out-connections for dead-end nodes using intelligent filtering:
  • Combined Strategy: Ignores generic tags (reference, documentation, tool, etc.), prioritizes keywords, requires similarity check
  • Smart Thresholds: 0.46 for strong signals (keywords or meaningful tags), 0.60 for weak signals (generic tags only), 0.58 for no signals
  • Quality Control: Prevents low-quality connections by requiring meaningful semantic signals
• Low Quality Note Remover: Removes irrelevant notes (CAPTCHA pages, error pages, spam)
• Summary Refiner: Refines similar summaries to make them more specific and distinct
• Corrupted Node Repairer: Repairs corrupted nodes (missing fields, invalid data)
• Relation Suggester: Finds semantically similar notes (cosine similarity ≥ 0.75) with dead-end node prioritization
• Summary Digester: Compresses nodes with >8 children into compact summaries

Automatic Scheduler

The system automatically runs memory enzymes every hour:

• Runs in background without blocking MCP operations
• Executes 19+ maintenance operations in optimized sequence
• Logs all maintenance activities with detailed metrics
• Gracefully handles errors and continues running
• Comprehensive Results: Returns detailed statistics for all operations (pruned links, merged duplicates, validated notes, quality scores, graph health score, dead-end nodes, etc.)

Researcher Agent

Deep web research for low-confidence queries with JIT context optimization:

• Automatic Triggering: Activates when retrieval confidence < threshold (default: 0.5)
• Manual Research: Available via research_and_store MCP tool
• Hybrid Approach: Uses MCP tools (if available) or HTTP-based fallbacks
• Web Search: Google Search API (primary) or DuckDuckGo HTTP (fallback)
• Content Extraction: Jina Reader (local Docker or cloud API) or Readability fallback
• PDF Support: Automatic PDF extraction using Unstructured (library or API)
• Automatic Note Creation: Research findings are automatically stored as atomic notes with metadata, keywords, and tags

📋 Installation

1. Install Dependencies

pip install -r requirements.txt

Graph Backend Selection

A-MEM supports three graph backends, selectable via GRAPH_BACKEND environment variable:

NetworkX (Default):

• ✅ Included by default (no extra installation)
• ✅ Cross-platform (Windows, Linux, macOS)
• ✅ Good for small to medium graphs (<10k nodes)

RustworkX (Recommended for Performance):

• ⚡ 3x-100x faster than NetworkX
• ✅ Windows-compatible
• ✅ Install with: pip install rustworkx
• ✅ Set GRAPH_BACKEND=rustworkx in .env

FalkorDB (Experimental - Not Fully Integrated/Tested):

• ⚠️ Proof-of-Concept Status - Funktional, aber noch nicht vollständig integriert und getestet
• 💾 Persistent storage (survives restarts)
• ⚠️ Nicht empfohlen für Production - Siehe docs/FALKORDB_POC_README.md für Details
• Linux/macOS: Install with pip install falkordblite, set GRAPH_BACKEND=falkordb
• Windows: Install with pip install falkordb redis, requires Redis with FalkorDB module (see docs/WINDOWS_FALKORDB_SETUP.md)
• ⚠️ Bekannte Einschränkungen: Memory Enzymes nutzen noch direkte graph.graph Zugriffe, Migration-Tool fehlt, Performance noch nicht getestet

Safe Graph Wrapper:

• 🛡️ Automatic edge case handling and dat