# MemoGraph

> Graph-based memory system for LLMs with knowledge graphs and semantic search

- **Type:** MCP server
- **Install:** `agentstack add mcp-indhar01-memograph`
- **Verified:** Pending review
- **Seller:** [Indhar01](https://agentstack.voostack.com/s/indhar01)
- **Installs:** 0
- **Latest version:** 0.1.1
- **License:** MIT
- **Upstream author:** [Indhar01](https://github.com/Indhar01)
- **Source:** https://github.com/Indhar01/MemoGraph
- **Website:** https://indhar01.github.io/web-memograph/

## Install

```sh
agentstack add mcp-indhar01-memograph
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MemoGraph 🧠

[](https://pypi.org/project/memograph/)
[](https://pypi.org/project/memograph/)
[](https://github.com/Indhar01/MemoGraph/blob/main/LICENSE)
[](https://modelcontextprotocol.io/registry)
[](https://modelcontextprotocol.io)
[](https://github.com/astral-sh/ruff)
[](https://github.com/pre-commit/pre-commit)
[](http://mypy-lang.org/)
[](https://docs.pytest.org/)
[](https://github.com/Indhar01/MemoGraph)

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

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

## ⚡ Try it in 60 seconds

```bash
pip install memograph
memograph quickstart
```

That'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:

```bash
memograph --vault ~/memograph-quickstart search "FastAPI dependency injection"
```

The 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.**

Re-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`.

## What you get

### As a solo user / knowledge worker

- A vault of human-readable markdown files — nothing proprietary, no lock-in. Your notes outlive any tool.
- 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.
- AI-assisted tagging, link suggestions, and gap detection that grow your knowledge base instead of letting it rot.
- A CLI and a web UI for browsing, editing, and visualizing the graph.

### As an AI agent / IDE user

- 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.
- Autonomous "auto-save" hooks that capture decisions and context from your AI conversations into the vault automatically.
- Per-conversation memory recall — your assistant can pull "what did we decide last week about X" without you copy-pasting context every time.

### As an enterprise / SaaS operator

- **Multi-tenant deployment** with filesystem-level isolation per tenant, end-to-end isolation tests, and a warm-LRU kernel cache.
- **OIDC + API-key authentication** with JWKS support (Auth0, Clerk, WorkOS, Keycloak, Azure AD, Okta), restrictive CORS, request-size caps, and rate limiting.
- **GDPR-compliant scheduled deletion**: tombstone-with-grace-period flow, automatic final backups, daily reaper, and an audit log of every deletion.
- **Observability built in**: OpenTelemetry traces + Prometheus `/metrics`, structured JSON logging with request IDs, and a separate `/healthz` / `/readyz` for orchestration.
- **Operations runbooks** shipped with the code: install, SSO setup, RBAC, backup-restore, and GDPR procedures.

## How consumers benefit

| You want to… | MemoGraph gives you… |
|---|---|
| Stop your AI assistant from forgetting context across conversations | Persistent vault + MCP server, plus optional auto-save hooks |
| Find a note across thousands when you only half-remember it | Hybrid retrieval (keyword + semantic + graph) with salience ranking |
| Connect related ideas without manual cross-linking | AI link suggestions, backlink graph, BFS traversal |
| Discover what's missing in your knowledge base | Gap detector + topic clustering + learning-path suggestions |
| Self-host a memory backend for a team or product | Web UI, FastAPI HTTP API, OpenAPI v1 contract, Docker compose |
| Ship MemoGraph to multiple paying customers | Multi-tenant kernel registry, OIDC, quotas (roadmap), GDPR runbook |
| Survive an SOC 2 audit conversation | Audit log with user + tenant binding, observability, security workflow, compliance roadmap doc |

## ✨ Capabilities at a glance

### Core memory engine

- **Graph-based memory** — bidirectional `[[wikilinks]]` build a navigable knowledge graph automatically.
- **Hybrid retrieval** — keyword + semantic embeddings + graph traversal, combined and re-ranked.
- **Memory types** inspired by cognitive science: episodic, semantic, procedural, fact.
- **Salience scoring** (0–1) that decays over time and boosts on access.
- **Smart indexing** — mtime-cached, only re-parses changed files.
- **Context compression** — token-budget-aware windowing for LLM prompts.
- **Markdown-native vault** — every memory is a `.md` file with YAML frontmatter; no proprietary format.

### AI features

- **Smart Auto-Organization Engine** — extract topics, people, action items, decisions, questions, sentiment, risks, ideas, and timeline events from memories.
- **AutoTagger** — suggest tags via semantic analysis, structure detection, and pattern learning.
- **LinkSuggester** — propose `[[wikilinks]]` to related notes; bidirectional opportunities included.
- **GapDetector** — surface missing topics, weak coverage, isolated notes, and unmade links.
- **Knowledge analysis** — vault stats, topic clustering, learning paths, connection analysis.

### Interfaces

- **Python API** — `MemoryKernel` with sync, async, and batch variants.
- **CLI** — 24+ commands for ingest, search, batch ops, import, export, backup, and AI features.
- **MCP server** — 30+ tools, stdio transport, drop-in for any MCP-compatible client.
- **Web UI** — React + D3 graph visualization, search, and editing (FastAPI backend + Vite frontend).
- **HTTP API** — versioned `/api/v1/`, OpenAPI snapshot in CI, ready for service-to-service integration.

### Enterprise & SaaS readiness

- **Multi-tenancy** with filesystem-isolated tenants, an LRU registry of warm kernels, per-tenant audit logs, and end-to-end isolation tests gating release.
- **Authentication** via OIDC (JWKS) or hashed API keys; per-route auth scope; identity bound into the audit log.
- **Web hardening** — restrictive CORS, slowapi rate limiting, request-size caps, structured JSON logging with request IDs, info-leak-free 500 handler.
- **Storage hardening** — path-traversal-safe vault writes, vault size soft/hard caps, schema-versioned cache files.
- **Scheduled deletion** for GDPR Art. 17: tombstone with configurable grace period, automatic final backup, daily reaper script, cancel-before-grace endpoint.
- **Observability** — OpenTelemetry FastAPI/asyncio auto-instrumentation, Prometheus `/metrics`, OTLP export.
- **Reliability** — concurrency audit, stress tests for concurrent writes, versioned backup format with integrity checks.
- **Distribution** — pinned-and-locked dependencies, Docker compose for self-host, security workflow (`bandit` + `pip-audit`).

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

## 🚀 Quick Start

> **Hosting it yourself?** [docs/HOSTING_GUIDE.md](docs/HOSTING_GUIDE.md)
> covers four genuinely-free paths — Oracle Free Tier, Cloudflare
> Tunnel + your hardware (recommended for most), GCP always-free
> stitch, and GitHub-repo-as-vault. Workspace identity via OIDC and
> Drive-as-portability-backup are documented in
> [docs/GOOGLE_WORKSPACE_SETUP.md](docs/GOOGLE_WORKSPACE_SETUP.md).

### Installation

```bash
pip install memograph
```

Install with optional dependencies:

```bash
# For OpenAI support
pip install memograph[openai]

# For Anthropic Claude support
pip install memograph[anthropic]

# For Ollama support
pip install memograph[ollama]

# For embedding support
pip install memograph[embeddings]

# Install everything
pip install memograph[all]
```

### Python Usage

```python
from memograph import MemoryKernel, MemoryType

# Initialize the kernel attached to your vault path
kernel = MemoryKernel("~/my-vault")

# Ingest all notes in the vault
stats = kernel.ingest()
print(f"Indexed {stats['indexed']} memories.")

# Programmatically add a new memory
kernel.remember(
    title="Meeting Note",
    content="Decided to use BFS graph traversal for retrieval.",
    memory_type=MemoryType.EPISODIC,
    tags=["design", "retrieval"]
)

# Retrieve context for an LLM query
context = kernel.context_window(
    query="how does retrieval work?",
    tags=["retrieval"],
    depth=2,
    top_k=8
)

print(context)
```

## 🔌 MCP Server (Model Context Protocol)

MemoGraph includes a full-featured MCP server for seamless integration with AI assistants like **Cline** and **Claude Desktop**.

**📖 New to MemoGraph MCP?** See the **[MCP User Guide](docs/MCP_USER_GUIDE.md)** for practical usage instructions and examples!

**🚨 Having connection issues?** See **[Setup & Troubleshooting Guide](docs/MCP_SETUP_TROUBLESHOOTING.md)** - Common fixes for "cannot connect" errors!

### 19 Available Tools

| Category | Tools | Description |
|----------|-------|-------------|
| **Search** | `search_vault`, `query_with_context` | Semantic search and context retrieval |
| **Create** | `create_memory`, `import_document` | Add memories and import documents |
| **Read** | `list_memories`, `get_memory`, `get_vault_info` | Browse and retrieve memories |
| **Update** | `update_memory` | Modify existing memories |
| **Delete** | `delete_memory` | Remove memories by ID |
| **Analytics** | `get_vault_stats` | Vault statistics and insights |
| **Discovery** | `list_available_tools` | List all available tools |
| **Autonomous** | `auto_hook_query`, `auto_hook_response`, `configure_autonomous_mode`, `get_autonomous_config` | Autonomous memory management |
| **Graph** | `relate_memories`, `search_by_graph`, `find_path` | Graph-native linking and traversal |
| **Bulk** | `bulk_create` | Create multiple memories in one call |

### Supported Clients

MemoGraph'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)**:

| Client | Format | Quick reference |
|---|---|---|
| Claude Code (CLI) | `mcpServers` | [`claude_code_config.json`](memograph/mcp/claude_code_config.json) |
| Claude Desktop | `mcpServers` | [`claude_desktop_config.json`](memograph/mcp/claude_desktop_config.json) |
| Cline | `mcp.servers` | [`cline_config.json`](memograph/mcp/cline_config.json) |
| Cursor | `mcpServers` | [`cursor_config.json`](memograph/mcp/cursor_config.json) |
| Windsurf | `mcpServers` | [`windsurf_config.json`](memograph/mcp/windsurf_config.json) |
| Continue.dev | `experimental.modelContextProtocolServers` | [`continue_config.json`](memograph/mcp/continue_config.json) |
| Zed | `context_servers` | [`zed_config.json`](memograph/mcp/zed_config.json) |
| VS Code (1.99+) | `servers` | [`vscode_config.json`](memograph/mcp/vscode_config.json) |
| Goose (Block) | YAML `extensions` | [`goose_config.yaml`](memograph/mcp/goose_config.yaml) |
| Roo Code | `mcpServers` | [`roo_code_config.json`](memograph/mcp/roo_code_config.json) |
| Gemini CLI | `mcpServers` | [`gemini_cli_config.json`](memograph/mcp/gemini_cli_config.json) |
| OpenAI Codex CLI | TOML `mcp_servers.` | [`codex_config.toml`](memograph/mcp/codex_config.toml) |
| LM Studio | `mcpServers` | [`lm_studio_config.json`](memograph/mcp/lm_studio_config.json) |
| Cherry Studio | UI form | [`cherry_studio_config.json`](memograph/mcp/cherry_studio_config.json) |
| IBM Bob Shell | `mcpServers` | [`bob_shell_config.json`](memograph/mcp/bob_shell_config.json) |

### Launching the MCP server

After `pip install memograph` (or `uv tool install memograph`), three launch commands are all equivalent:

```bash
memograph-mcp                              # console script (recommended)
python -m memograph.mcp.run_server         # module form (works with any Python)
uvx --from memograph memograph-mcp         # zero-install via uv
```

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

### Read-only mode

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

### Quick Setup for Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "memograph": {
      "command": "memograph-mcp",
      "env": {
        "MEMOGRAPH_VAULT": "/path/to/your/vault"
      }
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "memograph": {
      "command": "python",
      "args": ["-m", "memograph.mcp.run_server"],
      "env": {
        "MEMOGRAPH_VAULT": "/path/to/your/vault"
      }
    }
  }
}
```

### Quick Setup for Cline

Add to your `~/.cline/mcp_settings.json`:

```json
{
  "mcp": {
    "servers": {
      "memograph": {
        "command": "memograph-mcp",
        "env": {
          "MEMOGRAPH_VAULT": "/path/to/your/vault"
        }
      }
    }
  }
}
```

For **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)**.

### Install from MCP Registry

**NEW**: MemoGraph is now available in the official MCP Registry! 🎉

**Registry URL**: [https://github.com/modelcontextprotocol/servers/tree/main/src/memograph](https://github.com/modelcontextprotocol/servers)

```bash
pip install memograph
```

Then drop the snippet for your client into its config file (see the table above or [docs/MCP_CLIENTS.md](docs/MCP_CLIENTS.md)).

**Benefits of MCP Registry Listing:**
- ✅ Official registry backed by Anthropic, GitHub, and Microsoft
- ✅ Discoverable by all MCP-compatible clients
- ✅ Verified server card and metadata
- ✅ Direct link from PyPI package
- ✅ Trusted by the MCP community

**Note**: The registry uses the PyPI package version. When you `pip install memograph`, you automatically get the latest registry-listed version.

See **[MCP_REGISTRY_GUIDE.md](docs/MCP_REGISTRY_GUIDE.md)** for complete submission and configuration guide.

### Usage Examples

Once configured, use natural language with your AI assistant:

```
"Search my vault for memories about Python"
"Create a memory titled 'Project Ideas' with content '...'"
"Update memory abc-123 to have salience 0.9"
"Delete memory xyz-456"
"What tools are available?"
"Get vault statistics"
```

See **[CONFIG_REFERENCE.md](memograph/mcp/CONFIG_REFER

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Indhar01](https://github.com/Indhar01)
- **Source:** [Indhar01/MemoGraph](https://github.com/Indhar01/MemoGraph)
- **License:** MIT
- **Homepage:** https://indhar01.github.io/web-memograph/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Versions

- **0.1.1** — security scan: pending review — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-indhar01-memograph
- Seller: https://agentstack.voostack.com/s/indhar01
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.