{
  "markdown": "# MemoGraph 🧠\n\n<!-- mcp-name: io.github.Indhar01/memograph -->\n\n[![PyPI version](https://img.shields.io/pypi/v/memograph)](https://pypi.org/project/memograph/)\n[![Python Version](https://img.shields.io/pypi/pyversions/memograph)](https://pypi.org/project/memograph/)\n[![License](https://img.shields.io/github/license/Indhar01/MemoGraph)](https://github.com/Indhar01/MemoGraph/blob/main/LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-Published-blue)](https://modelcontextprotocol.io/registry)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)\n[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)\n[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue)](http://mypy-lang.org/)\n[![Tests](https://img.shields.io/badge/tests-pytest-orange)](https://docs.pytest.org/)\n[![Code Quality](https://img.shields.io/badge/code%20quality-A+-brightgreen)](https://github.com/Indhar01/MemoGraph)\n\n**MemoGraph turns a folder of markdown notes into a queryable, AI-ready knowledge graph.** It solves the LLM memory problem — your AI assistants forget last Tuesday's decision, can't find a related note across two projects, and re-derive the same insight again and again — by giving them a persistent, navigable, attribution-friendly memory layer that lives in plain markdown files you control.\n\nYou write notes the way you already do. MemoGraph indexes them, builds a graph from `[[wikilinks]]`, ranks them by salience, and serves them back to your LLM (or your team) on demand.\n\n## ⚡ Try it in 60 seconds\n\n```bash\npip install memograph\nmemograph quickstart\n```\n\nThat's it. The `quickstart` command drops a small, interconnected sample vault on your disk (15 notes about Python development, with real wikilinks between them), ingests it, and runs three live demo queries so you can see the graph + hybrid retrieval working before you decide whether to commit. Try this query in particular:\n\n```bash\nmemograph --vault ~/memograph-quickstart search \"FastAPI dependency injection\"\n```\n\nThe vault contains a note titled `FastAPI dependencies` (about `Depends(...)`) — the words \"dependency\" and \"injection\" never appear in any note's title. MemoGraph still finds it, because hybrid retrieval understands \"dependency injection\" semantically and the wikilink graph stitches related notes together. **That's the product, demonstrated in one query.**\n\nRe-run `memograph quickstart --force` any time to reset to a fresh demo. When you're ready, point MemoGraph at your real notes: `memograph --vault ~/your-notes ingest`.\n\n## What you get\n\n### As a solo user / knowledge worker\n\n- A vault of human-readable markdown files — nothing proprietary, no lock-in. Your notes outlive any tool.\n- Hybrid retrieval that combines keyword search, semantic similarity, and graph traversal so you find the right note even when you don't remember the exact words.\n- AI-assisted tagging, link suggestions, and gap detection that grow your knowledge base instead of letting it rot.\n- A CLI and a web UI for browsing, editing, and visualizing the graph.\n\n### As an AI agent / IDE user\n\n- A first-class **Model Context Protocol (MCP) server** with 30+ tools, working out of the box with Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Continue, Zed, VS Code, Goose, Gemini CLI, OpenAI Codex CLI, and others.\n- Autonomous \"auto-save\" hooks that capture decisions and context from your AI conversations into the vault automatically.\n- Per-conversation memory recall — your assistant can pull \"what did we decide last week about X\" without you copy-pasting context every time.\n\n### As an enterprise / SaaS operator\n\n- **Multi-tenant deployment** with filesystem-level isolation per tenant, end-to-end isolation tests, and a warm-LRU kernel cache.\n- **OIDC + API-key authentication** with JWKS support (Auth0, Clerk, WorkOS, Keycloak, Azure AD, Okta), restrictive CORS, request-size caps, and rate limiting.\n- **GDPR-compliant scheduled deletion**: tombstone-with-grace-period flow, automatic final backups, daily reaper, and an audit log of every deletion.\n- **Observability built in**: OpenTelemetry traces + Prometheus `/metrics`, structured JSON logging with request IDs, and a separate `/healthz` / `/readyz` for orchestration.\n- **Operations runbooks** shipped with the code: install, SSO setup, RBAC, backup-restore, and GDPR procedures.\n\n## How consumers benefit\n\n| You want to… | MemoGraph gives you… |\n|---|---|\n| Stop your AI assistant from forgetting context across conversations | Persistent vault + MCP server, plus optional auto-save hooks |\n| Find a note across thousands when you only half-remember it | Hybrid retrieval (keyword + semantic + graph) with salience ranking |\n| Connect related ideas without manual cross-linking | AI link suggestions, backlink graph, BFS traversal |\n| Discover what's missing in your knowledge base | Gap detector + topic clustering + learning-path suggestions |\n| Self-host a memory backend for a team or product | Web UI, FastAPI HTTP API, OpenAPI v1 contract, Docker compose |\n| Ship MemoGraph to multiple paying customers | Multi-tenant kernel registry, OIDC, quotas (roadmap), GDPR runbook |\n| Survive an SOC 2 audit conversation | Audit log with user + tenant binding, observability, security workflow, compliance roadmap doc |\n\n## ✨ Capabilities at a glance\n\n### Core memory engine\n\n- **Graph-based memory** — bidirectional `[[wikilinks]]` build a navigable knowledge graph automatically.\n- **Hybrid retrieval** — keyword + semantic embeddings + graph traversal, combined and re-ranked.\n- **Memory types** inspired by cognitive science: episodic, semantic, procedural, fact.\n- **Salience scoring** (0–1) that decays over time and boosts on access.\n- **Smart indexing** — mtime-cached, only re-parses changed files.\n- **Context compression** — token-budget-aware windowing for LLM prompts.\n- **Markdown-native vault** — every memory is a `.md` file with YAML frontmatter; no proprietary format.\n\n### AI features\n\n- **Smart Auto-Organization Engine** — extract topics, people, action items, decisions, questions, sentiment, risks, ideas, and timeline events from memories.\n- **AutoTagger** — suggest tags via semantic analysis, structure detection, and pattern learning.\n- **LinkSuggester** — propose `[[wikilinks]]` to related notes; bidirectional opportunities included.\n- **GapDetector** — surface missing topics, weak coverage, isolated notes, and unmade links.\n- **Knowledge analysis** — vault stats, topic clustering, learning paths, connection analysis.\n\n### Interfaces\n\n- **Python API** — `MemoryKernel` with sync, async, and batch variants.\n- **CLI** — 24+ commands for ingest, search, batch ops, import, export, backup, and AI features.\n- **MCP server** — 30+ tools, stdio transport, drop-in for any MCP-compatible client.\n- **Web UI** — React + D3 graph visualization, search, and editing (FastAPI backend + Vite frontend).\n- **HTTP API** — versioned `/api/v1/`, OpenAPI snapshot in CI, ready for service-to-service integration.\n\n### Enterprise & SaaS readiness\n\n- **Multi-tenancy** with filesystem-isolated tenants, an LRU registry of warm kernels, per-tenant audit logs, and end-to-end isolation tests gating release.\n- **Authentication** via OIDC (JWKS) or hashed API keys; per-route auth scope; identity bound into the audit log.\n- **Web hardening** — restrictive CORS, slowapi rate limiting, request-size caps, structured JSON logging with request IDs, info-leak-free 500 handler.\n- **Storage hardening** — path-traversal-safe vault writes, vault size soft/hard caps, schema-versioned cache files.\n- **Scheduled deletion** for GDPR Art. 17: tombstone with configurable grace period, automatic final backup, daily reaper script, cancel-before-grace endpoint.\n- **Observability** — OpenTelemetry FastAPI/asyncio auto-instrumentation, Prometheus `/metrics`, OTLP export.\n- **Reliability** — concurrency audit, stress tests for concurrent writes, versioned backup format with integrity checks.\n- **Distribution** — pinned-and-locked dependencies, Docker compose for self-host, security workflow (`bandit` + `pip-audit`).\n\n> See [docs/INSTALL_ENTERPRISE.md](docs/INSTALL_ENTERPRISE.md), [docs/SSO_SETUP.md](docs/SSO_SETUP.md), [docs/GDPR_RUNBOOK.md](docs/GDPR_RUNBOOK.md), [docs/BACKUP_RESTORE_RUNBOOK.md](docs/BACKUP_RESTORE_RUNBOOK.md), [docs/OBSERVABILITY_GUIDE.md](docs/OBSERVABILITY_GUIDE.md), and [docs/RBAC_GUIDE.md](docs/RBAC_GUIDE.md) for the operator-facing details.\n\n## 🚀 Quick Start\n\n> **Hosting it yourself?** [docs/HOSTING_GUIDE.md](docs/HOSTING_GUIDE.md)\n> covers four genuinely-free paths — Oracle Free Tier, Cloudflare\n> Tunnel + your hardware (recommended for most), GCP always-free\n> stitch, and GitHub-repo-as-vault. Workspace identity via OIDC and\n> Drive-as-portability-backup are documented in\n> [docs/GOOGLE_WORKSPACE_SETUP.md](docs/GOOGLE_WORKSPACE_SETUP.md).\n\n### Installation\n\n```bash\npip install memograph\n```\n\nInstall with optional dependencies:\n\n```bash\n# For OpenAI support\npip install memograph[openai]\n\n# For Anthropic Claude support\npip install memograph[anthropic]\n\n# For Ollama support\npip install memograph[ollama]\n\n# For embedding support\npip install memograph[embeddings]\n\n# Install everything\npip install memograph[all]\n```\n\n### Python Usage\n\n```python\nfrom memograph import MemoryKernel, MemoryType\n\n# Initialize the kernel attached to your vault path\nkernel = MemoryKernel(\"~/my-vault\")\n\n# Ingest all notes in the vault\nstats = kernel.ingest()\nprint(f\"Indexed {stats['indexed']} memories.\")\n\n# Programmatically add a new memory\nkernel.remember(\n    title=\"Meeting Note\",\n    content=\"Decided to use BFS graph traversal for retrieval.\",\n    memory_type=MemoryType.EPISODIC,\n    tags=[\"design\", \"retrieval\"]\n)\n\n# Retrieve context for an LLM query\ncontext = kernel.context_window(\n    query=\"how does retrieval work?\",\n    tags=[\"retrieval\"],\n    depth=2,\n    top_k=8\n)\n\nprint(context)\n```\n\n## 🔌 MCP Server (Model Context Protocol)\n\nMemoGraph includes a full-featured MCP server for seamless integration with AI assistants like **Cline** and **Claude Desktop**.\n\n**📖 New to MemoGraph MCP?** See the **[MCP User Guide](docs/MCP_USER_GUIDE.md)** for practical usage instructions and examples!\n\n**🚨 Having connection issues?** See **[Setup & Troubleshooting Guide](docs/MCP_SETUP_TROUBLESHOOTING.md)** - Common fixes for \"cannot connect\" errors!\n\n### 19 Available Tools\n\n| Category | Tools | Description |\n|----------|-------|-------------|\n| **Search** | `search_vault`, `query_with_context` | Semantic search and context retrieval |\n| **Create** | `create_memory`, `import_document` | Add memories and import documents |\n| **Read** | `list_memories`, `get_memory`, `get_vault_info` | Browse and retrieve memories |\n| **Update** | `update_memory` | Modify existing memories |\n| **Delete** | `delete_memory` | Remove memories by ID |\n| **Analytics** | `get_vault_stats` | Vault statistics and insights |\n| **Discovery** | `list_available_tools` | List all available tools |\n| **Autonomous** | `auto_hook_query`, `auto_hook_response`, `configure_autonomous_mode`, `get_autonomous_config` | Autonomous memory management |\n| **Graph** | `relate_memories`, `search_by_graph`, `find_path` | Graph-native linking and traversal |\n| **Bulk** | `bulk_create` | Create multiple memories in one call |\n\n### Supported Clients\n\nMemoGraph's MCP server is a stdio server — it runs alongside any MCP-compatible agentic CLI or editor. The full setup cookbook (config-file paths, format quirks, verification steps) lives in **[docs/MCP_CLIENTS.md](docs/MCP_CLIENTS.md)**:\n\n| Client | Format | Quick reference |\n|---|---|---|\n| Claude Code (CLI) | `mcpServers` | [`claude_code_config.json`](memograph/mcp/claude_code_config.json) |\n| Claude Desktop | `mcpServers` | [`claude_desktop_config.json`](memograph/mcp/claude_desktop_config.json) |\n| Cline | `mcp.servers` | [`cline_config.json`](memograph/mcp/cline_config.json) |\n| Cursor | `mcpServers` | [`cursor_config.json`](memograph/mcp/cursor_config.json) |\n| Windsurf | `mcpServers` | [`windsurf_config.json`](memograph/mcp/windsurf_config.json) |\n| Continue.dev | `experimental.modelContextProtocolServers` | [`continue_config.json`](memograph/mcp/continue_config.json) |\n| Zed | `context_servers` | [`zed_config.json`](memograph/mcp/zed_config.json) |\n| VS Code (1.99+) | `servers` | [`vscode_config.json`](memograph/mcp/vscode_config.json) |\n| Goose (Block) | YAML `extensions` | [`goose_config.yaml`](memograph/mcp/goose_config.yaml) |\n| Roo Code | `mcpServers` | [`roo_code_config.json`](memograph/mcp/roo_code_config.json) |\n| Gemini CLI | `mcpServers` | [`gemini_cli_config.json`](memograph/mcp/gemini_cli_config.json) |\n| OpenAI Codex CLI | TOML `mcp_servers.<name>` | [`codex_config.toml`](memograph/mcp/codex_config.toml) |\n| LM Studio | `mcpServers` | [`lm_studio_config.json`](memograph/mcp/lm_studio_config.json) |\n| Cherry Studio | UI form | [`cherry_studio_config.json`](memograph/mcp/cherry_studio_config.json) |\n| IBM Bob Shell | `mcpServers` | [`bob_shell_config.json`](memograph/mcp/bob_shell_config.json) |\n\n### Launching the MCP server\n\nAfter `pip install memograph` (or `uv tool install memograph`), three launch commands are all equivalent:\n\n```bash\nmemograph-mcp                              # console script (recommended)\npython -m memograph.mcp.run_server         # module form (works with any Python)\nuvx --from memograph memograph-mcp         # zero-install via uv\n```\n\n`memograph-mcp` and `memograph` are both registered as console scripts: the first starts the MCP server, the second is the CLI. They do not collide.\n\n### Read-only mode\n\nFor shared deployments or untrusted clients, set `MEMOGRAPH_READONLY=true`. The server refuses every vault-writing tool — `create_memory`, `import_document`, `update_memory`, `delete_memory`, `relate_memories`, `bulk_create`, `batch_update`, `batch_delete`, `import_backup_tool`, and the auto-save hooks — and returns a structured `{\"success\": false, \"readonly\": true, \"error\": \"...\"}` payload instead. Read tools (`search_vault`, `query_with_context`, `list_memories`, `get_memory`, analytics, graph traversal) stay fully functional.\n\n### Quick Setup for Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"memograph\": {\n      \"command\": \"memograph-mcp\",\n      \"env\": {\n        \"MEMOGRAPH_VAULT\": \"/path/to/your/vault\"\n      }\n    }\n  }\n}\n```\n\nIf the `memograph-mcp` binary isn't on the client's `PATH` (common when the client launches without your shell environment), use the explicit module form instead:\n\n```json\n{\n  \"mcpServers\": {\n    \"memograph\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"memograph.mcp.run_server\"],\n      \"env\": {\n        \"MEMOGRAPH_VAULT\": \"/path/to/your/vault\"\n      }\n    }\n  }\n}\n```\n\n### Quick Setup for Cline\n\nAdd to your `~/.cline/mcp_settings.json`:\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"memograph\": {\n        \"command\": \"memograph-mcp\",\n        \"env\": {\n          \"MEMOGRAPH_VAULT\": \"/path/to/your/vault\"\n        }\n      }\n    }\n  }\n}\n```\n\nFor **Claude Code, Cursor, Windsurf, Continue, Zed, VS Code, Goose, Gemini CLI, Codex CLI, LM Studio, Cherry Studio, and Bob Shell**, see **[docs/MCP_CLIENTS.md](docs/MCP_CLIENTS.md)**.\n\n### Install from MCP Registry\n\n**NEW**: MemoGraph is now available in the official MCP Registry! 🎉\n\n**Registry URL**: [https://github.com/modelcontextprotocol/servers/tree/main/src/memograph](https://github.com/modelcontextprotocol/servers)\n\n```bash\npip install memograph\n```\n\nThen drop the snippet for your client into its config file (see the table above or [docs/MCP_CLIENTS.md](docs/MCP_CLIENTS.md)).\n\n**Benefits of MCP Registry Listing:**\n- ✅ Official registry backed by Anthropic, GitHub, and Microsoft\n- ✅ Discoverable by all MCP-compatible clients\n- ✅ Verified server card and metadata\n- ✅ Direct link from PyPI package\n- ✅ Trusted by the MCP community\n\n**Note**: The registry uses the PyPI package version. When you `pip install memograph`, you automatically get the latest registry-listed version.\n\nSee **[MCP_REGISTRY_GUIDE.md](docs/MCP_REGISTRY_GUIDE.md)** for complete submission and configuration guide.\n\n### Usage Examples\n\nOnce configured, use natural language with your AI assistant:\n\n```\n\"Search my vault for memories about Python\"\n\"Create a memory titled 'Project Ideas' with content '...'\"\n\"Update memory abc-123 to have salience 0.9\"\n\"Delete memory xyz-456\"\n\"What tools are available?\"\n\"Get vault statistics\"\n```\n\nSee **[CONFIG_REFERENCE.md](memograph/mcp/CONFIG_REFERENCE.md)** for complete MCP configuration guide.\n\n### Using Auto-Save Hooks\n\nMemoGraph provides autonomous hooks to save conversations automatically:\n\n- ⚠️ **Important**: Hooks are passive tools - see [Autonomous Hooks Guide](docs/AUTONOMOUS_HOOKS_GUIDE.md) for setup\n- 📝 Quick fix: Add custom instructions to Claude Desktop (instructions in guide)\n- 🔧 Configure with `MEMOGRAPH_AUTONOMOUS_MODE=true`\n\n[Read the full Autonomous Hooks User Guide →](docs/AUTONOMOUS_HOOKS_GUIDE.md)\n\n## 🎯 CLI Usage\n\nMemoGraph comes with a powerful CLI for managing your vault and chatting with it.\n\n### Ingest\n\nIndex your markdown files into the graph database:\n\n```bash\nmemograph --vault ~/my-vault ingest\n```\n\nForce re-indexing all files:\n\n```bash\nmemograph --vault ~/my-vault ingest --force\n```\n\n### Remember\n\nQuickly add a memory from the command line:\n\n```bash\nmemograph --vault ~/my-vault remember \\\n    --title \"Team Sync\" \\\n    --content \"Discussed Q3 goals.\" \\\n    --tags planning q3\n```\n\n### Context Window\n\nGenerate context for a query:\n\n```bash\nmemograph --vault ~/my-vault context \\\n    --query \"What did we decide about the database?\" \\\n    --tags architecture \\\n    --depth 2 \\\n    --top-k 5\n```\n\n### Ask (Interactive Chat)\n\nStart an interactive chat session with your vault context:\n\n```bash\nmemograph --vault ~/my-vault ask --chat --provider ollama --model llama3\n```\n\nOr ask a single question:\n\n```bash\nmemograph --vault ~/my-vault ask \\\n    --query \"Summarize our design decisions\" \\\n    --provider claude \\\n    --model claude-3-5-sonnet-20240620\n```\n\n### Diagnostics\n\nCheck your environment and connection to LLM providers:\n\n```bash\nmemograph --vault ~/my-vault doctor\n\n### Import Documents\n\nImport documents (TXT, PDF, DOCX) and convert them to markdown:\n\n```bash\n# Import a single file\nmemograph --vault ~/my-vault import document.pdf --type episodic\n\n# Import entire folder\nmemograph --vault ~/my-vault import ~/Documents --recursive\n\n# Preview files without importing (dry run)\nmemograph --vault ~/my-vault import ~/Documents --dry-run\n\n# Auto-ingest after import\nmemograph --vault ~/my-vault import document.pdf --auto-ingest\n```\n\n### Batch Operations\n\nEfficiently manage multiple memories at once:\n\n```bash\n# Bulk create memories from JSON/CSV\nmemograph --vault ~/my-vault batch-create memories.json\n\n# Bulk update memories by filter\nmemograph --vault ~/my-vault batch-update \\\n    --filter-tags outdated \\\n    --add-tags reviewed \\\n    --salience 0.8\n\n# Bulk delete with safety checks\nmemograph --vault ~/my-vault batch-delete \\\n    --filter-type episodic \\\n    --filter-max-salience 0.3 \\\n    --dry-run\n```\n\n### Data Management\n\nExport, backup, and restore your vault:\n\n```bash\n# Export vault to JSON/CSV/Markdown\nmemograph --vault ~/my-vault export --format json --output backup.json\n\n# Create timestamped backup\nmemograph --vault ~/my-vault backup --output ./backups\n\n# Restore from backup\nmemograph --vault ~/my-vault import-backup backup.zip\n```\n\n### Configuration & Statistics\n\nManage settings and view vault analytics:\n\n```bash\n# View vault statistics\nmemograph --vault ~/my-vault stats\n\n# Configure settings\nmemograph config set embedding_provider openai\nmemograph config get embedding_provider\nmemograph config list\n\n# Manage profiles\nmemograph config profile create work --vault ~/work-vault\nmemograph config profile use work\n```\n\n### MCP Setup\n\nInteractive wizard to configure MCP server for Claude Desktop or Cline:\n\n```bash\n# Run interactive setup wizard\nmemograph setup-mcp\n\n# Verify MCP configuration\nmemograph verify-mcp\n```\n\n**📖 Complete CLI Documentation:** See **[CLI Usage Guide](MEMOGRAPH_CLI_USAGE_GUIDE.md)** for detailed documentation with 200+ examples covering all 24 commands.\n\n### 🤖 AI Features\n\nMemoGraph includes powerful AI-powered features to enhance your knowledge management workflow. See **[AI Features Guide](docs/guides/AI_FEATURES.md)** for complete documentation.\n\n#### 🏷️ AutoTagger - Intelligent Tag Suggestions\n\nAutomatically suggest relevant tags using semantic analysis, content structure, and existing patterns:\n\n```bash\n# Suggest tags for a note\nmemograph suggest-tags note.md\n\n# Apply high-confidence suggestions automatically\nmemograph suggest-tags note.md --apply\n\n# Adjust confidence threshold and limit\nmemograph suggest-tags note.md --min-confidence 0.5 --max-suggestions 10\n```\n\n**Features:** Frequency-based extraction • Semantic similarity • Structure detection • Pattern learning • Confidence scoring\n\n#### 🔗 LinkSuggester - Smart Wikilink Recommendations\n\nIntelligently recommend wikilinks to related notes using semantic similarity and graph analysis:\n\n```bash\n# Suggest links for a note\nmemograph suggest-links note.md\n\n# Apply suggestions automatically\nmemograph suggest-links note.md --apply\n\n# Show bidirectional link opportunities\nmemograph suggest-links note.md --show-bidirectional\n```\n\n**Features:** Semantic search • Keyword matching • Graph-based suggestions • Bidirectional detection • Target previews\n\n#### 🔍 GapDetector - Knowledge Base Analysis\n\nIdentify missing topics, weak coverage, and isolated notes in your vault:\n\n```bash\n# Detect all gaps\nmemograph detect-gaps\n\n# Focus on high-severity gaps\nmemograph detect-gaps --min-severity 0.7\n\n# Export results to JSON\nmemograph detect-gaps --output json > gaps.json\n```\n\n**Gap Types:** Missing Topics • Weak Coverage • Isolated Notes • Missing Links\n\n#### 📊 Knowledge Analysis - Comprehensive Insights\n\nGet comprehensive analysis of your entire knowledge base:\n\n```bash\n# Full analysis with all features\nmemograph analyze-knowledge\n\n# Export detailed report to JSON\nmemograph analyze-knowledge --output json > analysis.json\n```\n\n**Analysis Includes:** Vault statistics • Topic clustering • Learning paths • Gap detection • Connection analysis\n\n#### Python API for AI Features\n\n```python\nfrom memograph import MemoryKernel\nfrom memograph.ai import AutoTagger, LinkSuggester, GapDetector\n\nkernel = MemoryKernel(\"~/my-vault\")\nkernel.ingest()\n\n# Get tag suggestions\ntagger = AutoTagger(kernel, min_confidence=0.4)\nsuggestions = await tagger.suggest_tags(\n    content=\"Python is great for data science\",\n    title=\"Data Science with Python\"\n)\n\n# Get link suggestions\nsuggester = LinkSuggester(kernel, min_confidence=0.5)\nlinks = await suggester.suggest_links(\n    content=\"Python async programming tutorial\",\n    title=\"Async Python\"\n)\n\n# Detect knowledge gaps\ndetector = GapDetector(kernel, min_severity=0.5)\ngaps = await detector.detect_gaps()\n\n# Comprehensive analysis\nanalysis = await detector.analyze_knowledge_base()\n```\n\n**📖 Complete Documentation:**\n- **[AI Features Guide](docs/guides/AI_FEATURES.md)** - Comprehensive guide with examples\n- **[Web UI Guide](docs/guides/WEB_UI_GUIDE.md)** - Using AI features in the browser\n- **[MCP AI Tools Guide](docs/guides/MCP_AI_TOOLS.md)** - AI features for Claude & Cline\n\n**💡 Use Cases:** Auto-organize notes • Discover connections • Identify gaps • Maintain consistency • Build learning paths\n\n## 📖 Core Concepts\n\n### Memory Types\n\nMemoGraph supports different types of memories inspired by cognitive science:\n\n- **Episodic**: Personal experiences and events (e.g., meeting notes)\n- **Semantic**: Facts and general knowledge (e.g., documentation)\n- **Procedural**: How-to knowledge and processes (e.g., tutorials)\n- **Fact**: Discrete factual information (e.g., configuration values)\n\n### Graph Traversal\n\nThe library uses BFS (Breadth-First Search) to traverse your knowledge graph:\n\n```python\n# Retrieve nodes with depth=2 (2 hops from seed nodes)\nnodes = kernel.retrieve_nodes(\n    query=\"graph algorithms\",\n    depth=2,  # Traverse up to 2 levels deep\n    top_k=10  # Return top 10 relevant memories\n)\n```\n\n### Salience Scoring\n\nEach memory has a salience score (0.0-1.0) that represents its importance:\n\n```yaml\n---\ntitle: \"Critical Architecture Decision\"\nsalience: 0.9\nmemory_type: semantic\n---\n\nWe decided to use PostgreSQL for better ACID guarantees...\n```\n\n## 🏗️ Project Structure\n\n```\nMemoGraph/\n├── memograph/          # Main package\n│   ├── core/           # Core functionality\n│   │   ├── kernel.py   # Memory kernel\n│   │   ├── graph.py    # Graph implementation\n│   │   ├── retriever.py # Hybrid retrieval\n│   │   ├── indexer.py  # File indexing\n│   │   └── parser.py   # Markdown parsing\n│   ├── adapters/       # LLM and embedding adapters\n│   │   ├── embeddings/ # Embedding providers\n│   │   ├── frameworks/ # Framework integrations\n│   │   └── llm/        # LLM providers\n│   ├── storage/        # Storage and caching\n│   ├── mcp/            # MCP server implementation\n│   └── cli.py          # CLI implementation\n├── tests/              # Test suite\n├── examples/           # Example usage\n└── scripts/            # Utility scripts\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/Indhar01/MemoGraph.git\n   cd MemoGraph\n   ```\n\n2. Install in development mode:\n   ```bash\n   pip install -e \".[all,dev]\"\n   ```\n\n3. Install pre-commit hooks:\n   ```bash\n   pre-commit install\n   ```\n\n4. Run tests:\n   ```bash\n   pytest\n   ```\n\n### Code Quality\n\nWe maintain high code quality standards:\n\n- **Linting**: Ruff for fast Python linting\n- **Formatting**: Ruff formatter for consistent code style\n- **Type Checking**: MyPy for static type analysis\n- **Testing**: Pytest with comprehensive test coverage\n- **Pre-commit Hooks**: Automated checks before each commit\n\n## 📚 Documentation\n\n### Getting Started\n\n- **[Hosting Guide](docs/HOSTING_GUIDE.md)** - 💸 **Free hosting options** (Oracle Free Tier, Cloudflare Tunnel, GCP, GitHub-vault) with hardening checklist\n- **[Google Workspace Setup](docs/GOOGLE_WORKSPACE_SETUP.md)** - 🔐 OIDC identity + Drive portability backup\n- **[MCP Clients Guide](docs/MCP_CLIENTS.md)** - 🔌 **Setup snippets for 15+ agentic CLIs/editors** (Claude Code, Cursor, Windsurf, Continue, Zed, VS Code, Goose, Gemini CLI, Codex CLI, LM Studio, …)\n- **[MCP User Guide](docs/MCP_USER_GUIDE.md)** - ⭐ **Start here!** Complete guide for using MemoGraph MCP\n- **[Setup & Troubleshooting](docs/MCP_SETUP_TROUBLESHOOTING.md)** - 🚨 **Can't connect?** Step-by-step fixes for connection issues\n- **[MCP Testing Guide](docs/MCP_TESTING_GUIDE.md)** - Testing your MCP server after setup\n\n### For Developers & Contributors\n- **[MCP Registry Guide](docs/MCP_REGISTRY_GUIDE.md)** - Publishing to official MCP Registry\n- **[Versioning Strategy](docs/VERSIONING.md)** - Semantic versioning and release planning\n- **[AGENTS.md](AGENTS.md)** - Guide for AI agents working with this codebase\n- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project\n- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines\n- **[Security Policy](SECURITY.md)** - Security reporting and best practices\n- **[Changelog](CHANGELOG.md)** - Version history and changes\n\n## 🔒 Security\n\nSee our [Security Policy](SECURITY.md) for reporting vulnerabilities.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🌟 Acknowledgments\n\nInspired by the need for better memory management in LLM applications. Built with:\n\n- Graph-based knowledge representation\n- Hybrid retrieval strategies\n- Cognitive science principles\n\n## 📬 Contact & Support\n\n- **Issues**: [GitHub Issues](https://github.com/Indhar01/MemoGraph/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/Indhar01/MemoGraph/discussions)\n\n## 📣 Community & Feedback\n\nWe value community feedback and contributions! Here's how to get involved:\n\n### Report Issues\nFound a bug or have a feature request? [Open an issue](https://github.com/Indhar01/MemoGraph/issues/new) on GitHub.\n\n### Discussions\nJoin the conversation in [GitHub Discussions](https://github.com/Indhar01/MemoGraph/discussions):\n- Ask questions\n- Share use cases\n- Suggest improvements\n- Show what you've built\n\n### Contributing\nWe welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details on:\n- Code contributions\n- Documentation improvements\n- Bug reports and feature requests\n- Community support\n\n### Stay Updated\n- ⭐ Star the repository on [GitHub](https://github.com/Indhar01/MemoGraph)\n- 👁️ Watch for updates and releases\n- 📦 Follow the project on [PyPI](https://pypi.org/project/memograph/)\n- 🔗 Check out the [MCP Registry listing](https://github.com/modelcontextprotocol/servers/tree/main/src/memograph)\n\n## 🚦 Status\n\n**Current version**: 0.3.0\n\nSingle-tenant deployments are stable and recommended for production use.\nMulti-tenant deployments are feature-complete with end-to-end isolation\ntests gating the release; the public API will stabilise at v1.0.\n\n- ✅ Core functionality stable and tested (172+ tests across security, contract, and tenancy suites)\n- ✅ Whole-package type-checked with MyPy\n- ✅ Ruff lint + format + pre-commit hooks\n- ✅ OpenAPI v1 contract snapshot in CI\n- ✅ Multi-tenant isolation invariants verified by an e2e test suite\n- ⚠️ Public API may change in minor versions until v1.0.0\n\n### What landed recently\n\n- **Phase 3.7** — GDPR-compliant scheduled tenant deletion: tombstone-with-grace-period, daily reaper, automatic final backups.\n- **Phase 3.5** — `TenantRegistry` wired into the request path; non-admin routes resolve their kernel per-tenant.\n- **Phase 3 scaffold** — multi-tenancy ADR, `TenantStorage`, `TenantRegistry`, admin routes for tenant lifecycle.\n- **Phase 2** — OpenTelemetry + Prometheus, structured JSON logging, concurrency audit, stress tests.\n- **Phase 1** — OIDC + API-key auth, slowapi rate limiting, restrictive CORS, request-size caps, vault size caps, schema-versioned caches, OpenAPI v1 contract, security test suite.\n- **Phase 0** — path-traversal-safe vault writes, info-leak-free error handlers, pinned dependencies, Docker compose, security CI workflow.\n- 📦 **Published to the official MCP Registry** ([io.github.indhar01/memograph](https://github.com/modelcontextprotocol/servers/tree/main/src/memograph))\n\n---\n\nMade with ❤️ for better LLM memory management\n",
  "bytes": 30940,
  "sha": "fa8188f82d88ecd6a962532f212522350609a6835a3f625994226e48a7898a2a",
  "repo_slug": "indhar01/memograph",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_indhar01_memograph_25a6f8d0/readme"
}