hanzo-tools-memory¶

Unified memory and knowledge management for AI agents. Store, recall, and manage memories and facts across sessions.

Installation¶

pip install hanzo-tools-memory

Or as part of the full toolkit:

pip install hanzo-mcp[tools-all]

Overview¶

hanzo-tools-memory provides:

Memory - Episodic memory for storing and recalling information
Facts - Knowledge base management for structured information
Scopes - Session, project, and global memory levels
Summarization - Automatic content summarization

Quick Start¶

# Store a memory
memory(action="create", data={"content": "User prefers dark mode"})

# Recall memories
memory(action="recall", query="user preferences")

# Store facts
memory(action="store_facts", data={
    "facts": ["API rate limit is 100/hour"],
    "kb_name": "api_docs"
})

# Recall facts
memory(action="facts", query="rate limit")

Memory Actions¶

create¶

Store new memories:

memory(action="create", data={
    "content": "User prefers TypeScript over JavaScript",
    "scope": "project"  # session, project, or global
})

# Store multiple memories
memory(action="create", data={
    "statements": [
        "User works in Python",
        "Project uses FastAPI",
        "Prefers minimal dependencies"
    ]
})

recall¶

Search and retrieve memories:

# Simple query
memory(action="recall", query="user preferences")

# With scope filter
memory(action="recall", query="coding style", scope="project")

# Limit results
memory(action="recall", query="API endpoints", limit=5)

# Multiple queries (parallel search)
memory(action="recall", data={
    "queries": ["database schema", "API design", "error handling"]
})

update¶

Modify existing memories:

memory(action="update", data={
    "updates": [
        {"id": "mem_123", "statement": "User now prefers light mode"},
        {"id": "mem_456", "statement": "Updated API endpoint"}
    ]
})

delete¶

Remove memories:

memory(action="delete", data={
    "ids": ["mem_123", "mem_456"]
})

manage¶

Batch operations (create, update, delete in one call):

memory(action="manage", data={
    "creations": ["New fact 1", "New fact 2"],
    "updates": [{"id": "mem_1", "statement": "Updated"}],
    "deletions": ["mem_old1", "mem_old2"]
})

Facts & Knowledge Bases¶

store_facts¶

Store structured facts in knowledge bases:

memory(action="store_facts", data={
    "facts": [
        "Python uses indentation for blocks",
        "FastAPI supports async/await"
    ],
    "kb_name": "python_basics",
    "scope": "project"
})

facts¶

Query knowledge bases:

# Query specific knowledge base
memory(action="facts", query="async patterns", kb_name="python_basics")

# Query all knowledge bases
memory(action="facts", query="error handling")

# With scope
memory(action="facts", query="API docs", scope="global")

kb_manage¶

Manage knowledge bases:

# Create knowledge base
memory(action="kb_manage", data={
    "action": "create",
    "kb_name": "api_docs",
    "description": "API documentation and endpoints"
})

# List knowledge bases
memory(action="kb_manage", data={"action": "list", "scope": "project"})

# Delete knowledge base
memory(action="kb_manage", data={"action": "delete", "kb_name": "old_docs"})

Summarization¶

summarize¶

Summarize content and store in memory:

memory(action="summarize", data={
    "content": "Long discussion about API design decisions...",
    "topic": "API Design Decisions",
    "scope": "project",
    "auto_facts": True  # Auto-extract facts
})

Scopes¶

Memories exist at three levels:

Scope	Persistence	Use Case
`session`	Current session only	Temporary context
`project`	Per-project	Project-specific knowledge
`global`	All projects	User preferences, global facts

# Session memory (temporary)
memory(action="create", data={
    "content": "Currently debugging auth issue",
    "scope": "session"
})

# Project memory (persistent)
memory(action="create", data={
    "content": "Project uses PostgreSQL",
    "scope": "project"
})

# Global memory (shared)
memory(action="create", data={
    "content": "User prefers Vim keybindings",
    "scope": "global"
})

Storage¶

Memories are stored in:

~/.hanzo/memory/session/ - Session memories
~/.hanzo/memory/project/<project>/ - Project memories
~/.hanzo/memory/global/ - Global memories

Examples¶

Context Building¶

# At start of session, recall relevant context
memories = memory(action="recall", data={
    "queries": [
        "project architecture",
        "recent changes",
        "pending tasks"
    ],
    "scope": "project"
})

Learning User Preferences¶

# Store preference when learned
memory(action="create", data={
    "content": "User prefers functional programming style",
    "scope": "global"
})

# Later, recall preferences
prefs = memory(action="recall", query="coding style preferences")

Project Documentation¶

# Store project facts
memory(action="store_facts", data={
    "facts": [
        "Database: PostgreSQL 15",
        "ORM: SQLAlchemy 2.0",
        "API Framework: FastAPI",
        "Auth: JWT tokens"
    ],
    "kb_name": "tech_stack",
    "scope": "project"
})

# Query later
stack = memory(action="facts", query="what database", kb_name="tech_stack")

Session Summarization¶

# At end of session, summarize work
memory(action="summarize", data={
    "content": conversation_history,
    "topic": "Session Summary - Auth Implementation",
    "scope": "project"
})