m-memory 0.1.0

A dual-layer memory system for AI agents with incremental clustering, graph-based retrieval, and conflict resolution.

m-memory — Dual-Layer Memory System for AI Agents

A dual-layer memory system for AI agents with incremental clustering, graph-based retrieval, and automatic conflict resolution.

Quick Start (5 minutes)

pip install -e ".[dev]"

from memory_system.config import MemorySystemConfig
from memory_system.vector_store import NumpyVectorStore
from memory_system.graph_engine import NetworkXGraphStore
from memory_system.fake_llm import FakeLLMAdapter
from memory_system.retrieval import MemoryRetrievalEngineImpl

# 1. Create the engine
config = MemorySystemConfig()
config.embedding_dim = 8  # small dim for demo
engine = MemoryRetrievalEngineImpl(
    config=config,
    vector_store=NumpyVectorStore(dim=config.embedding_dim),
    graph_store=NetworkXGraphStore(),
    llm=FakeLLMAdapter(),
)

# 2. Ingest memories
id1 = engine.ingest("my cat", "My cat loves sleeping in the sun")
id2 = engine.ingest("my dog", "My dog enjoys running at the park")
id3 = engine.ingest("cat food", "I feed my cat premium dry food")

# 3. Search memories
result = engine.search("tell me about my cat")
for node, score in zip(result.nodes, result.scores):
    print(f"[{score:.3f}] {node.summary}: {node.content}")

Output example:

[0.812] cat food: I feed my cat premium dry food
[0.745] my cat: My cat loves sleeping in the sun

Core Concepts

Concept	Description
MemoryNode	One dialogue turn: A (summary for screening) + C (content for retrieval)
Bucket	Dynamic cluster with a Medoid (representative node)
Medoid	The node closest to all others in its bucket — used for coarse search
Cross-bucket Edge	Soft link between related buckets — no physical duplication
Conflict Resolution	Detects contradictions, marks old info as stale (not deleted)

Architecture

Query → [Layer 1: Bucket coarse screen] → [In-bucket fine search]
         → [Graph associative expansion] → [Layer 2: Conflict resolution]

See ARCHITECTURE_DESIGN.md for the full design spec.

API Reference

• MemoryRetrievalEngine — ingest(), search(), resolve_conflicts()
• BucketManager — bucket lifecycle and assignment
• VectorStore — embedding and similarity search
• GraphStore — graph traversal and edge management

Development

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

# Run tests
pytest tests/

# Type check
mypy --strict memory_system/

# Lint
ruff check memory_system/

See CONTRIBUTING.md for the full development harness guide.

License

MIT — see pyproject.toml.