🧠 MemoryHub

Persistent memory for AI agents. One API. Every agent remembers.

Quick Start · Features · [API Docs#-api-reference) · Deployment · Contributing

Every AI agent wakes up with amnesia. MemoryHub fixes that. 🧠⚡

Give your Claude, LangChain, AutoGPT, CrewAI, AutoGen, or custom agents a brain that persists across sessions. Store conversations, facts, preferences, decisions, and relationships — all through a simple REST API or Python SDK.

Keywords: ai agent memory, persistent memory, llm memory, ai long-term memory, agent context, rag alternative, conversation memory, ai knowledge base, agent state management, llm context window, ai memory system, agent memory store, ai persistent storage, langchain memory, ai agent framework, llm agent memory, ai assistant memory, context persistence, agent memory api, ai memory management

⚡ Why MemoryHub?

Problem	Without MemoryHub	With MemoryHub
🧠 Agent memory	Resets every session	Persists forever
🔍 Context retrieval	Manual RAG setup	Built-in semantic search
🏷️ Memory organization	Flat text chunks	Typed, tagged, scored
🔗 Entity relationships	Manual tracking	Automatic graph
🔄 Deduplication	None	Auto-consolidation
🛡️ Security	Afterthought	Built-in auth + detection
🐍 Integration	Custom glue code	SDK + CLI + REST API

✨ Features

🧠 Core Memory Engine

Episodic Memory — Conversations, events, interactions with timestamps
Semantic Memory — Facts, knowledge, preferences that persist across sessions
Relational Memory — Entity graphs — who works where, what uses what
Procedural Memory — Workflows, how-to guides, patterns

🔍 Smart Search & Recall

Full-Text Search — ILIKE-based content search across memories, tags, entities
Semantic Search — Sentence transformer embeddings (all-MiniLM-L6-v2) for similarity
Entity Extraction — Auto-detect people, emails, URLs, tech keywords, project names
Sentiment Detection — Rule-based sentiment scoring (-1.0 to 1.0)

📋 Context Building

Context Assembly — Build relevant context bundles for agent prompts
Importance Scoring — 5-level importance system (Trivial → Critical)
Recency Prioritization — Recent memories weighted higher
Token Estimation — Estimate context size before injection

🔄 Memory Management

Consolidation — Auto-deduplicate, archive stale, importance decay/boost
Tagging — Flexible tag-based organization
Namespaces — Multi-agent isolation with separate data spaces
Expiration — TTL-based memory expiration

🛡️ Security & Privacy

API Key Auth — Secure agent registration and authentication
Sensitive Data Detection — Auto-detect API keys, passwords, tokens, private keys, SSH keys, database URLs
Optional Redaction — Auto-redact sensitive content before storage
Namespace Isolation — Agents can't access each other's memories

🔌 Integration Ready

Python SDK — pip install memoryhub → from memoryhub import MemoryHubClient
CLI Tool — memoryhub command with full feature support
REST API — OpenAPI/Swagger docs at /docs
Docker — One-command deployment
Async Support — Async methods for async agents

🚀 Quick Start

Install

pip install memoryhub

Start the Server

memoryhub serve
# 🧠 Server starts at http://localhost:7860
# 📖 API docs at http://localhost:7860/docs

Register Your Agent

memoryhub register --name "my-assistant" --namespace "john"
# Save the API key! 🔑

Use the SDK

from memoryhub import MemoryHubClient

# Connect
client = MemoryHubClient(api_key="mhub_xxx", base_url="http://localhost:7860")

# 🧠 Store memories
client.remember("John prefers dark mode", category="preference", importance=4)
client.remember("Project Alpha uses FastAPI + PostgreSQL", category="fact")
client.remember("Decided to use SQLite for MVP", category="decision", importance=5)

# 🔍 Search memories
results = client.recall("John preferences")
for m in results["memories"]:
    print(f"  [{m['category']}] {m['content']}")

# 📋 Build context for your agent
context = client.context_as_text("What does John prefer?")
# → "📋 Context Summary
#    Found 2 relevant memories (semantic).
#    - [preference] John prefers dark mode [92%]"

# 🔗 Create entity relationships
client.relate("John", "works_at", "Acme Corp")
client.relate("Project Alpha", "uses", "FastAPI")

# 📊 Get stats
print(client.stats())
# → {'total_memories': 3, 'total_relations': 2, ...}

Convenience Methods

# Pre-configured memory types
client.remember_preference("John likes dark themes")
client.remember_fact("The API runs on port 7860")
client.remember_decision("Using SQLite for MVP, migrate later")
client.remember_error("Connection timeout after 30s")
client.remember_conversation("User: How do I configure this?")

🏗️ Architecture

┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│  Claude 🤖   │  │  LangChain  │  │  CrewAI 👥  │  │  Custom Bot │
│  Agent A    │  │  Agent B    │  │  Agent C    │  │  Agent D    │
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                │                │
       └────────────────┴────────────────┴────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │    MemoryHub 🧠     │
                    │                     │
                    │  ┌───────────────┐  │
                    │  │   REST API    │  │  ← FastAPI + OpenAPI
                    │  │   Python SDK  │  │  ← memoryhub package
                    │  │   CLI Tool    │  │  ← memoryhub command
                    │  └───────────────┘  │
                    │                     │
                    │  ┌───────────────┐  │
                    │  │ Memory Engine │  │
                    │  │ • Episodic    │  │  ← conversations, events
                    │  │ • Semantic    │  │  ← facts, preferences
                    │  │ • Relational  │  │  ← entity graphs
                    │  │ • Procedural  │  │  ← workflows, patterns
                    │  └───────────────┘  │
                    │                     │
                    │  ┌───────────────┐  │
                    │  │ Search Engine │  │
                    │  │ • Full-Text   │  │  ← ILIKE search
                    │  │ • Semantic    │  │  ← embeddings (MiniLM)
                    │  │ • Entity Ext. │  │  ← auto-extraction
                    │  └───────────────┘  │
                    │                     │
                    │  ┌───────────────┐  │
                    │  │ Storage Layer │  │
                    │  │ • SQLite 📦   │  │  ← local-first
                    │  │ • PostgreSQL  │  │  ← production scale
                    │  └───────────────┘  │
                    └─────────────────────┘

📖 API Reference

Authentication

# Register a new agent → get API key
POST /api/v1/agents
{
  "name": "my-agent",
  "namespace": "my-project",
  "description": "My helpful AI assistant"
}
# Response: { "api_key": "mhub_xxxxxxxx", ... }

# Use in all requests
X-API-Key: mhub_xxxxxxxx

Memories

Endpoint	Method	Description
`/api/v1/memories`	`POST`	🧠 Store a new memory
`/api/v1/memories/bulk`	`POST`	📦 Store multiple memories
`/api/v1/memories/search`	`GET`	🔍 Search memories
`/api/v1/memories/{id}`	`GET`	📄 Get a specific memory
`/api/v1/memories/{id}`	`PATCH`	✏️ Update a memory
`/api/v1/memories/{id}`	`DELETE`	🗑️ Delete a memory
`/api/v1/memories/context/build`	`GET`	📋 Build context bundle
`/api/v1/memories/stats`	`GET`	📊 Get statistics
`/api/v1/memories/consolidate`	`POST`	🔄 Run consolidation

Relations

Endpoint	Method	Description
`/api/v1/memories/relations`	`POST`	🔗 Create relationship
`/api/v1/memories/relations/search`	`GET`	🕸️ Search relationships
`/api/v1/memories/relations/{id}`	`DELETE`	❌ Delete relationship

System

Endpoint	Method	Description
`/health`	`GET`	💚 Health check
`/docs`	`GET`	📖 Interactive API docs
`/redoc`	`GET`	📕 ReDoc documentation
`/openapi.json`	`GET`	📋 OpenAPI schema

💻 CLI Usage

# 🔧 Configure
memoryhub configure

# 🧠 Store memories
memoryhub remember "John prefers dark mode" --type semantic --category preference --importance 4
memoryhub remember "Meeting notes from today" --tags "meeting,project-alpha"

# 🔍 Search
memoryhub recall "John" --limit 5
memoryhub recall "project" --type semantic --text

# 📋 Build context
memoryhub context "What does John like?" --text

# 🔗 Create relationships
memoryhub relate "John" "works_at" "Acme Corp"
memoryhub relate "Project Alpha" "uses" "FastAPI"

# 📊 Stats & management
memoryhub stats
memoryhub consolidate
memoryhub health

# 🚀 Start server
memoryhub serve --host 0.0.0.0 --port 7860 --reload

🤝 Integration Examples

With Claude (Anthropic)

import anthropic
from memoryhub import MemoryHubClient

memory = MemoryHubClient(api_key="mhub_xxx")
claude = anthropic.Anthropic()

def chat(user_message, session_id="default"):
    # Get relevant context from memory
    context = memory.context_as_text(user_message, max_memories=5)

    # Store user message
    memory.remember(user_message, category="conversation", session_id=session_id)

    # Call Claude with context
    response = claude.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        system=f"You are a helpful assistant. Relevant context:\n{context}",
        messages=[{"role": "user", "content": user_message}]
    )

    # Store response
    memory.remember(response.content[0].text, category="conversation", session_id=session_id)
    return response.content[0].text

With LangChain

from langchain.agents import AgentExecutor, create_openai_agent
from langchain.tools import Tool
from memoryhub import MemoryHubClient

memory = MemoryHubClient(api_key="mhub_xxx")

tools = [
    Tool(name="Remember", func=lambda c: str(memory.remember(c)),
         description="Store a memory. Input: content to remember."),
    Tool(name="Recall", func=lambda q: memory.recall_as_text(q),
         description="Search memories. Input: search query."),
]
# Use tools in your LangChain agent...

With OpenAI

from openai import OpenAI
from memoryhub import MemoryHubClient

memory = MemoryHubClient(api_key="mhub_xxx")
client = OpenAI()

def chat(user_message):
    context = memory.context_as_text(user_message)
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": f"Context:\n{context}"},
            {"role": "user", "content": user_message}
        ]
    )
    memory.remember(f"Q: {user_message}\nA: {response.choices[0].message.content}")
    return response.choices[0].message.content

With CrewAI

from crewai import Agent, Task, Crew
from memoryhub import MemoryHubClient

memory = MemoryHubClient(api_key="mhub_xxx")

# Use memory in crew tasks...
context = memory.context_as_text("research topic")
researcher = Agent(
    role="Researcher",
    goal="Research with persistent memory",
    backstory=f"Previous findings:\n{context}"
)

🚀 Deployment

Docker (One Command)

docker run -d \
  --name memoryhub \
  -p 7860:7860 \
  -v memoryhub-data:/app/data \
  -e MEMORYHUB_SECRET_KEY=$(openssl rand -hex 32) \
  memoryhub/memoryhub:latest

Docker Compose

docker compose up -d

Cloud

AWS ECS/Fargate — See deployment guide
Google Cloud Run — gcloud run deploy memoryhub
Fly.io — fly deploy
Railway — railway up
DigitalOcean — App Platform ready

See docs/DEPLOYMENT.md for detailed guides.

🔧 Configuration

Environment Variables

Variable	Default	Description
`MEMORYHUB_HOST`	`0.0.0.0`	Server host
`MEMORYHUB_PORT`	`7860`	Server port
`MEMORYHUB_SECRET_KEY`	auto-generated	JWT/API key secret
`MEMORYHUB_DATABASE_URL`	`sqlite+aiosqlite:///./memoryhub.db`	Database URL
`MEMORYHUB_EMBEDDING_MODEL`	`all-MiniLM-L6-v2`	Sentence transformer model
`MEMORYHUB_ENABLE_SENSITIVE_DETECTION`	`true`	Auto-detect sensitive data
`MEMORYHUB_REDACT_ON_STORE`	`false`	Auto-redact before storage
`MEMORYHUB_CONSOLIDATION_INTERVAL_HOURS`	`24`	Hours between auto-consolidation
`MEMORYHUB_IMPORTANCE_DECAY_DAYS`	`90`	Days before importance decays
`MEMORYHUB_DEBUG`	`false`	Debug mode

🧠 Memory Types & Categories

Types

Type	Use For
`episodic`	Events, conversations, interactions
`semantic`	Facts, knowledge, preferences
`relational`	Entity connections
`procedural`	How-to, workflows, patterns

📊 Why MemoryHub vs Alternatives?

Feature	MemoryHub	LangChain Memory	Vector DB + RAG	Custom Solution
Setup complexity	⭐ Simple	⭐⭐ Medium	⭐⭐⭐ Complex	⭐⭐⭐⭐ Very complex
Persistent storage	✅ Built-in	❌ Session only	⚠️ DIY	⚠️ DIY
Memory types	✅ 4 types	❌ Text only	❌ Chunks only	⚠️ Custom
Entity relationships	✅ Built-in	❌ No	❌ No	⚠️ DIY
Semantic search	✅ Built-in	❌ No	✅ Yes	⚠️ DIY
Auto-consolidation	✅ Built-in	❌ No	❌ No	⚠️ DIY
Sensitive detection	✅ Built-in	❌ No	❌ No	⚠️ DIY
Multi-agent	✅ Namespaces	❌ No	⚠️ DIY	⚠️ DIY
Auth & security	✅ API keys	❌ No	⚠️ DIY	⚠️ DIY
Python SDK	✅	⚠️ Part of LangChain	❌ No	⚠️ DIY
CLI tool	✅	❌ No	❌ No	⚠️ DIY
Docker ready	✅	N/A	⚠️ Depends	⚠️ DIY

📦 Project Structure

memoryhub/
├── memoryhub/
│   ├── api/               # FastAPI routes
│   │   ├── memories.py    # Memory CRUD, search, context, relations
│   │   ├── admin.py       # Agent registration, namespaces
│   │   └── deps.py        # Auth dependencies, middleware
│   ├── core/              # Business logic
│   │   ├── auth.py        # API key management
│   │   ├── client.py      # Python SDK client
│   │   ├── consolidation.py # Memory dedup, archive, decay
│   │   ├── context.py     # Context bundle builder
│   │   ├── embeddings.py  # Sentence transformer engine
│   │   ├── extraction.py  # Entity & sentiment extraction
│   │   └── sensitive.py   # Sensitive data detection
│   ├── models/            # Pydantic data models
│   │   ├── memory.py      # Memory, Relation, Search, Stats
│   │   └── auth.py        # Agent, Token, Namespace
│   ├── storage/           # Database layer
│   │   ├── database.py    # SQLAlchemy async engine
│   │   ├── models.py      # ORM table models
│   │   └── memory_store.py # CRUD operations
│   ├── utils/             # Utilities
│   │   └── sensitive.py   # Pattern matching for secrets
│   ├── cli/               # CLI tool
│   │   └── main.py        # Typer CLI commands
│   ├── config.py          # Environment configuration
│   └── app.py             # FastAPI application
├── tests/                 # Test suite
├── examples/              # Integration examples
├── docs/                  # Documentation
├── assets/                # Logos, images
├── .github/               # CI/CD, templates
├── Dockerfile             # Docker build
├── docker-compose.yml     # Docker Compose
├── pyproject.toml         # Package config
├── README.md              # This file
├── CONTRIBUTING.md        # Contribution guide
├── CHANGELOG.md           # Version history
├── SECURITY.md            # Security policy
└── LICENSE                # MIT License

🗺️ Roadmap

v1.0 ✅ (Current)

v1.5 🔮 (Next)

JavaScript/TypeScript SDK (npm)
Web dashboard for memory browsing
PostgreSQL production support
Memory import/export (JSON, CSV)
Rate limiting and quotas

v2.0 🚀 (Future)

Memory visualization graph
Plugin system for custom extractors
Webhook events for memory changes
Multi-tenant cloud deployment
Memory sharing between agents
Advanced analytics and insights

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Areas we need help with:

🔌 Integrations (LangChain, LlamaIndex, CrewAI, AutoGen)
📦 JavaScript/TypeScript SDK
🎨 Web dashboard
📊 Analytics and visualization
📖 Documentation and tutorials
🧪 Testing and quality

📄 License

MIT License — see LICENSE for details.

🙏 Acknowledgments

FastAPI — API framework
SQLAlchemy — ORM
Sentence Transformers — Embeddings
Typer — CLI framework
Rich — Terminal formatting

Built to solve AI amnesia. One memory at a time. 🧠⚡

⭐ Star on GitHub · 📦 PyPI · 📖 Docs · 💬 Discord

Category	Description
`conversation`	Chat messages, dialogues
`decision`	Decisions made, rationale
`preference`	User preferences, settings
`fact`	Objective facts, knowledge
`task`	Tasks, todos, assignments
`error`	Errors, bugs, learnings
`learning`	Insights, discoveries
`person`	Information about people
`project`	Project-related info
`system`	System configuration, state

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github		.github
assets		assets
docs		docs
examples		examples
memoryhub		memoryhub
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

🧠 MemoryHub

⚡ Why MemoryHub?

✨ Features

🧠 Core Memory Engine

🔍 Smart Search & Recall

📋 Context Building

🔄 Memory Management

🛡️ Security & Privacy

🔌 Integration Ready

🚀 Quick Start

Install

Start the Server

Register Your Agent

Use the SDK

Convenience Methods

🏗️ Architecture

📖 API Reference

Authentication

Memories

Relations

System

💻 CLI Usage

🤝 Integration Examples

With Claude (Anthropic)

With LangChain

With OpenAI

With CrewAI

🚀 Deployment

Docker (One Command)

Docker Compose

Cloud

🔧 Configuration

Environment Variables

🧠 Memory Types & Categories

Types

Categories

📊 Why MemoryHub vs Alternatives?

📦 Project Structure

🗺️ Roadmap

v1.0 ✅ (Current)

v1.5 🔮 (Next)

v2.0 🚀 (Future)

🤝 Contributing

📄 License

🙏 Acknowledgments

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages