<div align="center"> <img src="assets/logo.svg" alt="MemoryHub" width="200"/>

🧠 MemoryHub

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

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

</div>

---

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 |

Categories

| 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 |

---

📊 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)

• [x] Core memory CRUD operations
• [x] Semantic search with embeddings
• [x] Entity extraction and relationships
• [x] Memory consolidation engine
• [x] Context builder for agents
• [x] Python SDK with convenience methods
• [x] CLI tool with rich output
• [x] Multi-agent namespace isolation
• [x] API key authentication
• [x] Sensitive data detection
• [x] Docker support
• [x] Comprehensive test suite

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

---

<div align="center">

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

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

</div>