agentic-box

Open Source

memora

<h1 align="center"><img src="media/memora_new.gif" width="60" alt="Memora Logo" align="absmiddle"> Memora</h1> "You never truly know the value of a moment until it becomes a memory." Give your AI agents persistent memory An MCP memory layer for agents: structured storage, semantic retrieval, graph relations, and source-backed cross-session context. <a href="https://github.com/agentic-box/memora/releases"><img src="https://img.shields.io/github/v/tag/agentic-box/memora?label=version&color=blue" alt="Version"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a> <a href="https://github.com/thedotmack/awesome-claude-code"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code"></a> <img src="media/memora-absorb-digest-flow.gif" alt="Memora absorb and digest flow" width="820"> Absorb agent work into durable graph memory, then use <code>memory_digest(topic)</code> to retrieve relevant memories, TODOs/issues, related edges, and source IDs. <a href="#features">Features</a> · <a href="#preview">Preview</a> · <a href="#install">Install</a> · <a href="#usage">Usage</a> · <a href="#configuration">Config</a> · <a href="#live-graph-server">Live Graph</a> · <a href="#cloud-graph">Cloud Graph</a> · <a href="#chat-with-memories">Chat</a> · <a href="#semantic-search--embeddings">Semantic Search</a> · <a href="#document-storage">Documents</a> · <a href="#llm-deduplication">LLM Dedup</a> · <a href="#memory-linking">Linking</a> · <a href="#neovim-integration">Neovim</a> ## Features **Core Storage** - 💾 **Persistent Storage** - SQLite with optional cloud sync (S3, R2, D1) - 📂 **Hierarchical Organization** - Section/subsection structure with auto-hierarchy assignment - 📦 **Export/Import** - Backup and restore with merge strategies **Search & Intelligence** - 🔍 **Semantic Search** - Vector embeddings (TF-IDF, sentence-transformers, OpenAI) - 🎯 **Advanced Queries** - Full-text, date ranges, tag filters (AND/OR/NOT), hybrid search - 🔀 **Cross-references** - Auto-linked related memories based on similarity - 🤖 **LLM Deduplication** - Find and merge duplicates with AI-powered comparison - 🔗 **Memory Linking** - Typed edges, importance boosting, and cluster detection **Document Storage** - 📄 **Structured Documents** - Store markdown documents as searchable fragment trees (claims, plan items, references, risks) - 🔒 **Fragment Integrity** - Guards against accidental delete/merge/absorb of document fragments - 🔍 **Granular Search** - Individual claims and findings are semantically searchable while the full document remains retrievable as a unit **Tools & Visualization** - ⚡ **Memory Automation** - Structured tools for TODOs, issues, and sections - 🕸️ **Knowledge Graph** - Interactive visualization with Mermaid rendering and cluster overlays - 🌐 **Live Graph Server** - Built-in HTTP server with cloud-hosted option (D1/Pages) - 💬 **Chat with Memories** - RAG-powered chat panel with LLM tool calling to search, create, update, and delete memories via streaming chat - 📡 **Event Notifications** - Poll-based system for inter-agent communication - 📊 **Statistics & Analytics** - Tag usage, trends, and connection insights - 🧠 **Memory Insights** - Activity summary, stale detection, consolidation suggestions, and LLM-powered pattern analysis - 📜 **Action History** - Track all memory operations (create, update, delete, merge, boost, link) with grouped timeline view ## Preview <img src="media/demo.gif" alt="Memora memory graph demo" width="320"> <img src="media/demo2.gif" alt="Memora memory interaction demo" width="320"> ## Install ```bash pip install git+https://github.com/agentic-box/memora.git ``` Includes cloud storage (S3/R2) and OpenAI embeddings out of the box. ```bash # Optional: local embeddings (offline, ~2GB for PyTorch) pip install "memora[local]" @ git+https://github.com/agentic-box/memora.git ``` <details id="usage"> <summary><big><big>Usage</big></big></summary> The server runs automatically when configured in Claude Code. Manual invocation: ```bash # Default (stdio mode for MCP) memora-server # With graph visualization server memora-server --graph-port 8765 # HTTP transport (alternative to stdio) memora-server --transport streamable-http --host 127.0.0.1 --port 8080 ``` </details> <details id="configuration"> <summary><big><big>Configuration</big></big></summary> ### Claude Code Add to `.mcp.json` in your project root: **Local DB:** ```json { "mcpServers": { "memora": { "command": "memora-server", "args": [], "env": { "MEMORA_DB_PATH": "~/.local/share/memora/memories.db", "MEMORA_ALLOW_ANY_TAG": "1", "MEMORA_GRAPH_PORT": "8765" } } } } ``` **Cloud DB (Cloudflare D1) - Recommended:** ```json { "mcpServers": { "memora": { "command": "memora-server", "args": ["--no-graph"], "env": { "MEMORA_STORAGE_URI": "d1://<account-id>/<database-id>", "CLOUDFLARE_API_TOKEN": "<your-api-token>", "MEMORA_ALLOW_ANY_TAG": "1" } } } } ``` With D1, use `--no-graph` to disable the local visualization server. Instead, use the hosted graph at your Cloudflare Pages URL (see [Cloud Graph](#cloud-graph)). **Cloud DB (S3/R2) - Sync mode:** ```json { "mcpServers": { "memora": { "command": "memora-server", "args": [], "env": { "AWS_PROFILE": "memora", "AWS_ENDPOINT_URL": "https://<account-id>.r2.cloudflarestorage.com", "MEMORA_STORAGE_URI": "s3://memories/memories.db", "MEMORA_CLOUD_ENCRYPT": "true", "MEMORA_ALLOW_ANY_TAG": "1", "MEMORA_GRAPH_PORT": "8765" } } } } ``` ### Codex CLI Add to `~/.codex/config.toml`: ```toml [mcp_servers.memora] command = "memora-server" # or full path: /path/to/bin/memora-server args = ["--no-graph"] env = { AWS_PROFILE = "memora", AWS_ENDPOINT_URL = "https://<account-id>.r2.cloudflarestorage.com", MEMORA_STORAGE_URI = "s3://memories/memories.db", MEMORA_CLOUD_ENCRYPT = "true", MEMORA_ALLOW_ANY_TAG = "1", } ``` </details> <details id="environment-variables"> <summary><big><big>Environment Variables</big></big></summary> | Variable | Description | |------------------------|-----------------------------------------------------------------------------| | `MEMORA_DB_PATH` | Local SQLite database path (default: `~/.local/share/memora/memories.db`) | | `MEMORA_STORAGE_URI` | Storage URI: `d1://<account>/<db-id>` (D1) or `s3://bucket/memories.db` (S3/R2) | | `CLOUDFLARE_API_TOKEN` | API token for D1 database access (required for `d1://` URI) | | `MEMORA_CLOUD_ENCRYPT` | Encrypt database before uploading to cloud (`true`/`false`) | | `MEMORA_CLOUD_COMPRESS`| Compress database before uploading to cloud (`true`/`false`) | | `MEMORA_CACHE_DIR` | Local cache directory for cloud-synced database | | `MEMORA_ALLOW_ANY_TAG` | Allow any tag without validation against allowlist (`1` to enable) | | `MEMORA_TAG_FILE` | Path to file containing allowed tags (one per line) | | `MEMORA_TAGS` | Comma-separated list of allowed tags | | `MEMORA_GRAPH_PORT` | Port for the knowledge graph visualization server (default: `8765`) | | `MEMORA_EMBEDDING_MODEL` | Embedding backend: `openai` (default), `sentence-transformers`, or `tfidf` | | `SENTENCE_TRANSFORMERS_MODEL` | Model for sentence-transformers (default: `all-MiniLM-L6-v2`) | | `OPENAI_API_KEY` | API key for OpenAI embeddings and LLM deduplication | | `OPENAI_BASE_URL` | Base URL for OpenAI-compatible APIs (OpenRouter, Azure, etc.) | | `OPENAI_EMBEDDING_MODEL` | OpenAI embedding model (default: `text-embedding-3-small`) | | `MEMORA_LLM_ENABLED` | Enable LLM-powered deduplication comparison (`true`/`false`, default: `true`) | | `MEMORA_LLM_MODEL` | Model for deduplication comparison (default: `gpt-4o-mini`) | | `CHAT_MODEL` | Model for the chat panel (default: `deepseek/deepseek-chat`, falls back to `MEMORA_LLM_MODEL`) | | `AWS_PROFILE` | AWS credentials profile from `~/.aws/credentials` (useful for R2) | | `AWS_ENDPOINT_URL` | S3-compatible endpoint for R2/MinIO | | `R2_PUBLIC_DOMAIN` | Public domain for R2 image URLs | </details> <details id="semantic-search--embeddings"> <summary><big><big>Semantic Search & Embeddings</big></big></summary> Memora supports three embedding backends: | Backend | Install | Quality | Speed | |---------|---------|---------|-------| | `openai` (default) | Included | High quality | API latency | | `sentence-transformers` | `pip install memora[local]` | Good, runs offline | Medium | | `tfidf` | Included | Basic keyword matching | Fast | **Automatic:** Embeddings and cross-references are computed automatically when you `memory_create`, `memory_update`, or `memory_create_batch`. **Manual rebuild required** when: - Changing `MEMORA_EMBEDDING_MODEL` after memories exist - Switching to a different sentence-transformers model ```bash # After changing embedding model, rebuild all embeddings memory_rebuild_embeddings # Then rebuild cross-references to update the knowledge graph memory_rebuild_crossrefs ``` </details> <details id="live-graph-server"> <summary><big><big>Live Graph Server</big></big></summary> A built-in HTTP server starts automatically with the MCP server, serving an interactive knowledge graph visualization. <table> <tr> <td align="center"><img src="media/ui_details.png" alt="Details Panel" width="400"> Details Panel</td> <td align="center"><img src="media/ui_timeline.png" alt="Timeline Panel" width="400"> Timeline Panel</td> </tr> </table> **Access locally:** ``` http://localhost:8765/graph ``` **Remote access via SSH:** ```bash ssh -L 8765:localhost:8765 user@remote # Then open http://localhost:8765/graph in your browser ``` **Configuration:** ```json { "env": { "MEMORA_GRAPH_PORT": "8765" } } ``` To disable: add `"--no-graph"` to args in your MCP config. ### Graph UI Features - **Details Panel** - View memory content, metadata, tags, and related memories - **Timeline Panel** - Browse memories chronologically, click to highlight in graph - **History Panel** - Action log of all operations with grouped consecutive entries and clickable memory references (deleted memories shown as strikethrough) - **Chat Panel** - Ask questions about your memories using RAG-powered LLM chat with streaming responses and clickable `[Memory #ID]` references - **Time Slider** - Filter memories by date range, drag to explore history - **Real-time Updates** - Graph, timeline, and history update via SSE when memories change - **Filters** - Tag/section dropdowns, zoom controls - **Mermaid Rendering** - Code blocks render as diagrams ### Node Colors - 🟣 **Tags** - Purple shades by tag - 🔴 **Issues** - Red (open), Orange (in progress), Green (resolved), Gray (won't fix) - 🔵 **TODOs** - Blue (open), Orange (in progress), Green (completed), Red (blocked) Node size reflects connection count. </details> <details id="cloud-graph"> <summary><big><big>Cloud Graph (Recommended for D1)</big></big></summary> When using Cloudflare D1 as your database, the graph visualization is hosted on Cloudflare Pages - no local server needed. **Benefits:** - Access from anywhere (no SSH tunneling) - Real-time updates via WebSocket - Multi-database support via `?db=` parameter - Secure access with Cloudflare Zero Trust **Setup:** 1. **Create D1 database:** ```bash npx wrangler d1 create memora-graph npx wrangler d1 execute memora-graph --file=memora-graph/schema.sql ``` 2. **Deploy Pages:** ```bash cd memora-graph npx wrangler pages deploy ./public --project-name=memora-graph ``` 3. **Configure bindings** in Cloudflare Dashboard: - Pages → memora-graph → Settings → Bindings - Add D1: `DB_MEMORA` → your database - Add R2: `R2_MEMORA` → your bucket (for images) 4. **Configure MCP** with D1 URI: ```json { "env": { "MEMORA_STORAGE_URI": "d1://<account-id>/<database-id>", "CLOUDFLARE_API_TOKEN": "<your-token>" } } ``` **Access:** `https://memora-graph.pages.dev` **Secure with Zero Trust:** 1. Cloudflare Dashboard → Zero Trust → Access → Applications 2. Add application for `memora-graph.pages.dev` 3. Create policy with allowed emails 4. Pages → Settings → Enable Access Policy See [`memora-graph/`](memora-graph/) for detailed setup and multi-database configuration. </details> <details id="chat-with-memories"> <summary><big><big>Chat with Memories</big></big></summary> Ask questions about your knowledge base directly from the graph UI. The chat panel uses RAG (Retrieval-Augmented Generation) to search relevant memories and stream LLM responses with tool calling support. - **Toggle** via the floating chat icon at bottom-right - **Semantic search** finds the most relevant memories as context - **Streaming responses** with clickable `[Memory #ID]` references that focus the graph node - **Tool calling** — the LLM can create, update, and delete memories directly from chat (e.g., "save this as a memory", "delete memory #42", "update memory #10 with...") - Works on both the local server and Cloudflare Pages deployment **Configure the chat model:** | Backend | Variable | Default | |---------|----------|---------| | Local server | `CHAT_MODEL` env var | Falls back to `MEMORA_LLM_MODEL` | | Cloudflare Pages | `CHAT_MODEL` in `wrangler.toml` | `deepseek/deepseek-chat` | Requires an OpenAI-compatible API (`OPENAI_API_KEY` + `OPENAI_BASE_URL` for local, `OPENROUTER_API_KEY` secret for Cloudflare). The chat model must support tool use (function calling). </details> <details id="llm-deduplication"> <summary><big><big>LLM Deduplication</big></big></summary> Find and merge duplicate memories using AI-powered semantic comparison: ```python # Find potential duplicates (uses cross-refs + optional LLM analysis) memory_find_duplicates(min_similarity=0.7, max_similarity=0.95, limit=10, use_llm=True) # Merge duplicates (append, prepend, or replace strategies) memory_merge(source_id=123, target_id=456, merge_strategy="append") ``` **LLM Comparison** analyzes memory pairs and returns: - `verdict`: "duplicate", "similar", or "different" - `confidence`: 0.0-1.0 score - `reasoning`: Brief explanation - `suggested_action`: "merge", "keep_both", or "review" Works with any OpenAI-compatible API (OpenAI, OpenRouter, Azure, etc.) via `OPENAI_BASE_URL`. </details> <details id="document-storage"> <summary><big><big>Document Storage</big></big></summary> Store structured documents (research reports, architecture decisions, post-mortems) as searchable fragment trees: ```python # Store a markdown document — auto-parsed into typed fragments memory_store_document( content="# Research Report\n\n## Evidence Table\n| Claim | Confidence |\n...", document_key="research/memora-enhancements-2026-04-08", tags=["memora/research"] ) # Returns: {root_id: 230, fragment_count: 100, node_map: {claim: [...], plan_item: [...], ...}} # Retrieve the full document or specific fragment types memory_get_document(document_key="research/memora-enhancements-2026-04-08") memory_get_document(document_key="...", node_kinds=["claim"], content_mode="full") # Delete a document and all its fragments memory_delete_document(document_key="research/memora-enhancements-2026-04-08") ``` **How it works:** The parser splits markdown by structure — tables become individual claims, numbered lists become plan items, URL lists become references, and risk sections become risk fragments. Each fragment is independently searchable via `memory_semantic_search` while the full document is retrievable as a unit. **Fragment types:** `claim`, `plan_item`, `reference`, `section_chunk`, `risk` **Integrity guards:** Document fragments are protected from accidental modification: - `memory_delete` requires `force=True` for fragments - `memory_merge` refuses to merge fragments - `memory_absorb` excludes fragments from similarity matching - `memory_find_duplicates` and `memory_detect_supersessions` skip fragments - Graph UI hides fragments, shows only the document root node </details> <details id="memory-automation-tools"> <summary><big><big>Memory Automation Tools</big></big></summary> Structured tools for common memory types: ```python # Create a TODO with status and priority memory_create_todo(content="Implement feature X", status="open", priority="high", category="backend") # Create an issue with severity memory_create_issue(content="Bug in login flow", status="open", severity="major", component="auth") # Create a section placeholder (hidden from graph) memory_create_section(content="Architecture", section="docs", subsection="api") ``` </details> <details id="memory-insights"> <summary><big><big>Memory Insights</big></big></summary> Analyze stored memories and surface actionable insights: ```python # Full analysis with LLM-powered pattern detection memory_insights(period="7d", include_llm_analysis=True) # Quick summary without LLM (faster, no API key needed) memory_insights(period="1m", include_llm_analysis=False) ``` Returns: - **Activity summary** — memories created in the period, grouped by type and tag - **Open items** — open TODOs and issues with stale detection (configurable via `MEMORA_STALE_DAYS`, default 14) - **Consolidation candidates** — similar memory pairs that could be merged - **LLM analysis** — themes, focus areas, knowledge gaps, and a summary (requires `OPENAI_API_KEY`) </details> <details id="memory-linking"> <summary><big><big>Memory Linking</big></big></summary> Manage relationships between memories: ```python # Create typed edges between memories memory_link(from_id=1, to_id=2, edge_type="implements", bidirectional=True) # Edge types: references, implements, supersedes, extends, contradicts, related_to # Remove links memory_unlink(from_id=1, to_id=2) # Boost memory importance for ranking memory_boost(memory_id=42, boost_amount=0.5) # Detect clusters of related memories memory_clusters(min_cluster_size=2, min_score=0.3) ``` </details> <details id="knowledge-graph-export"> <summary><big><big>Knowledge Graph Export (Optional)</big></big></summary> For offline viewing, export memories as a static HTML file: ```python memory_export_graph(output_path="~/memories_graph.html", min_score=0.25) ``` This is optional - the Live Graph Server provides the same visualization with real-time updates. </details> <details id="neovim-integration"> <summary><big><big>Neovim Integration</big></big></summary> Browse memories directly in Neovim with Telescope. Copy the plugin to your config: ```bash # For kickstart.nvim / lazy.nvim cp nvim/memora.lua ~/.config/nvim/lua/kickstart/plugins/ ``` **Usage:** Press `<leader>sm` to open the memory browser with fuzzy search and preview. Requires: `telescope.nvim`, `plenary.nvim`, and `memora` installed in your Python environment. </details>

AI Agents Vector Databases

410 Github Stars

Software by agentic-box

memora