{
  "markdown": "<p align=\"center\">\n  <img src=\"docs/screenshots/banner.png\" width=\"300\" alt=\"Memento — Remember Everything, Forget Nothing\" />\n</p>\n\n# Memento\n\n> **Give your AI tools a persistent memory — so every session starts where the last one left off.**\n\n[![Version](https://img.shields.io/badge/version-v0.1.0--alpha-orange)](CHANGELOG.md)\n[![Go Version](https://img.shields.io/badge/go-1.23%2B-00ADD8?logo=go)](https://go.dev)\n[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n[![Docker](https://img.shields.io/badge/docker-compose-2496ED?logo=docker)](docker-compose.yml)\n[![MCP](https://img.shields.io/badge/MCP-compatible-8B5CF6)](https://modelcontextprotocol.io)\n\nYour AI starts fresh every session. Memento fixes that.\n\nIt runs on your machine, connects to any MCP-compatible AI tool, and builds a persistent knowledge graph from your conversations — entities, relationships, decisions, and context that survive every session restart.\n\n**No cloud. No API keys required. No subscriptions. Your data stays on your machine.**\n\n---\n\n## Quick Start\n\n**Prerequisites:** [Docker](https://docker.com) — or — [Go 1.23+](https://go.dev) + [Node.js 18+](https://nodejs.org) + [Ollama](https://ollama.ai)\n\n```bash\ngit clone https://github.com/scrypster/memento.git\ncd memento\n./launch.sh\n```\n\nThe script detects your environment, runs preflight checks, builds everything, and **prints the exact command to connect your AI tool at the end.** First run downloads Ollama models (~5 GB). After that, starts in seconds.\n\n### Your first memory\n\nOnce connected, try this in Claude:\n\n```\n\"We're using PostgreSQL — chose it for pgvector support.\"\n```\n\nClose the tab. Open a new session. Ask:\n\n```\n\"What database are we using?\"\n```\n\nYour AI already knows. No re-explaining. No context window tricks.\n\nClose the tab. Open a new session.\n\n```\nYou: \"What database are we using?\"\n\n→ Your AI already knows: \"PostgreSQL — you chose it for pgvector support.\"\n  No re-explaining. No context window tricks. It just remembers.\n```\n\nBehind the scenes, Memento built this automatically:\n\n![Graph Explorer](docs/screenshots/graph.png)\n\nEvery entity gets wired into a knowledge graph — people, tools, projects, decisions — with confidence scores and timestamps.\n\n---\n\n## Connect Your Tools\n\nOpen **http://localhost:6363/integrations** — the web UI generates configs, download buttons, and connection testing for every client:\n\n![Integrations](docs/screenshots/integrations.png)\n\n| Client | Setup |\n|---|---|\n| **Claude Code** | Run `./launch.sh` — it prints the exact copy-paste command at the end. Example form: `` claude mcp add memento -- `pwd`/memento-mcp `` |\n| **Claude Desktop** | Download config → drop in `~/Library/Application Support/Claude/` |\n| **Cursor** | Download config → drop in `.cursor/mcp.json` + optional Cursor Rules file |\n| **Windsurf** | Download config → drop in `.codeium/windsurf/mcp_config.json` |\n| **OpenClaw** | Add to `~/.openclaw/mcp.json` under `mcpServers` — same pattern as Claude Desktop |\n| **Generic MCP** | Any MCP client — same pattern: command path + `MEMENTO_DATA_PATH` env var |\n\n> The integrations page generates ready-to-paste configs with your actual binary paths and data directories. It also has connection testing, troubleshooting, and per-project workspace scoping.\n\n### Make Claude Code proactive (recommended)\n\nThe MCP connection makes tools *available*, but Claude won't use them automatically. Add this to `~/.claude/CLAUDE.md` to make Claude store decisions and recall context without being asked:\n\n```markdown\n## Memento MCP — Persistent Memory\n\nThe `memento` MCP server provides persistent cross-session memory. Use these tools proactively — don't wait to be asked.\n\n**Store** (`store_memory`) when the user:\n- States a preference or working style (\"I prefer X\", \"always use Y format\")\n- Makes an architectural or technical decision\n- Establishes project context that should survive session restarts\n- Explicitly says \"remember this\" or similar\n\n**Recall** (`recall_memory` or `find_related`) when:\n- Starting a session for a known project — query for relevant context before diving in\n- About to make a recommendation — check for existing preferences first\n- The user asks about past decisions, choices, or \"what did we decide about X\"\n- Something seems like it may have been discussed in a prior session\n\n**Don't store:** transient debug output, in-progress exploration, or anything session-specific that won't matter next time.\n\nMemories are searchable immediately after storing. Enrichment (entity/relationship extraction) runs asynchronously via local Ollama.\n```\n\n> The web UI at **Integrations → Claude Code → Make it proactive** generates a version with your specific paths and connection settings, plus a download button.\n\nSee the full integration guides: [Claude Code](docs/integrations/claude-code.md) | [Claude Desktop](docs/integrations/claude-desktop.md) | [Cursor & Windsurf](docs/integrations/cursor-windsurf.md) | [OpenClaw](docs/integrations/openclaw.md)\n\n### Team memory — shared knowledge across your whole engineering team\n\nPoint everyone's AI tools at the same Memento instance and your team's decisions, conventions, and context become shared knowledge — queryable by anyone, attributable to anyone.\n\nEvery memory is tagged with who stored it. Memento auto-detects this from your git config, or you can set it explicitly:\n\n```bash\nexport MEMENTO_USER=alice   # or set in your shell profile\n```\n\nOr in your MCP config:\n```json\n\"env\": { \"MEMENTO_USER\": \"alice\" }\n```\n\nOnce set, you can ask:\n\n```\nWhat did Bob decide about the auth service this week?\nrecall_memory(created_by=\"bob\", created_after=\"2024-01-14T00:00:00Z\")\n```\n\n**Setup:** Each teammate runs Memento pointing at the same PostgreSQL database. Personal context stays personal (use a separate personal connection). Shared architectural decisions, conventions, and project context go into the shared connection.\n\nSee the [team setup guide](docs/team-setup.md) for full PostgreSQL configuration.\n\n---\n\n## What Your AI Gets\n\nOnce connected, your AI has **20 tools** it can call — no prompting required:\n\n### Core memory operations\n\n| Tool | What it does |\n|---|---|\n| `store_memory` | Persist a decision or piece of context — enrichment happens async, returns in <10ms |\n| `recall_memory` | Retrieve memories by ID, natural-language query, or paginated list with filters |\n| `find_related` | Hybrid search: full-text + semantic vector + RRF ranking |\n| `update_memory` | Edit content, tags, or metadata of an existing memory |\n| `forget_memory` | Soft-delete a memory (with grace period) or hard-delete permanently |\n\n### Search and intelligence\n\n| Tool | What it does |\n|---|---|\n| `traverse_memory_graph` | Follow entity relationships to discover contextually connected memories (multi-hop BFS) |\n| `detect_contradictions` | Find conflicting relationships, superseded-but-active memories, temporal impossibilities |\n| `explain_reasoning` | Surface why specific memories were retrieved for a query |\n| `get_session_context` | \"Where did I leave off?\" — recent memories grouped by topic |\n\n### Memory lifecycle\n\n| Tool | What it does |\n|---|---|\n| `update_memory_state` | Move through lifecycle: `planning → active → paused / blocked / completed → archived` |\n| `evolve_memory` | Create a new version that supersedes the old one — preserves full history |\n| `consolidate_memories` | LLM-assisted merge of multiple related memories into one coherent record |\n| `get_evolution_chain` | View the full version history of a memory from original to latest |\n\n### Soft delete and recovery\n\n| Tool | What it does |\n|---|---|\n| `restore_memory` | Recover a soft-deleted memory |\n| `list_deleted_memories` | Browse soft-deleted memories that can still be restored |\n| `retry_enrichment` | Re-run entity extraction on a memory that previously failed |\n\n### Project management\n\n| Tool | What it does |\n|---|---|\n| `create_project` | Create a project memory with optional pre-created phases |\n| `add_project_item` | Add epics, phases, tasks, steps, or milestones under a project |\n| `get_project_tree` | Retrieve the full nested hierarchy of a project |\n| `list_projects` | List all projects, optionally filtered by lifecycle state |\n\n**Store returns in <10ms.** Enrichment — entity extraction, relationship mapping, embedding generation — runs asynchronously. Your AI is never blocked.\n\n---\n\n## What It Looks Like\n\n### Auto-extracted entities — zero manual input\n\n![Entities](docs/screenshots/entities.png)\n\nPeople, projects, tools, organizations, languages, APIs — extracted automatically from your AI conversations. No tagging required.\n\n### Relationship intelligence\n\n![Relationships](docs/screenshots/relationships.png)\n\nYour AI knows who `works_on` what, which tools `depend_on` which services, and what the current state of each decision is — with confidence scores and timestamps.\n\n### The dashboard\n\n![Dashboard](docs/screenshots/dashboard.png)\n\nLive enrichment queue, entity browser, relationship explorer, and graph visualizer — all in the web UI.\n\n---\n\n## Why Memento\n\n### vs. Mem0\n\nMem0 requires cloud API keys and a paid plan for production use. Memento runs entirely on your machine with Ollama — no API keys, no cloud, no per-memory pricing. Memento also ships a full web UI with graph visualization, entity browser, and one-click integration setup. Mem0 has no web interface.\n\n### vs. Zep / Graphiti\n\nZep requires Neo4j or FalkorDB for its knowledge graph. Memento uses SQLite (zero deps) or PostgreSQL — no graph database to manage. Zep's open-source version is limited; the full feature set requires Zep Cloud.\n\n### vs. Built-in AI memory (ChatGPT, Claude)\n\nBuilt-in memory is a flat list of facts with no relationships, no search, no graph, and no way to export or control your data. Memento gives you a structured knowledge graph you own, with hybrid search and full lifecycle management.\n\n### vs. Writing docs or wikis\n\nMemento captures context automatically as you work — no manual effort. It builds relationships between concepts instead of isolated pages, and it's designed to be queried by LLMs, not just humans.\n\n---\n\n## How It Works\n\n```\n┌─────────────────────────────────────────────────────┐\n│  Your AI tool (Cursor / Claude Code / Windsurf / …) │\n└─────────────────────────┬───────────────────────────┘\n                          │  MCP (JSON-RPC 2.0 over stdio)\n┌─────────────────────────▼───────────────────────────┐\n│                   MCP Server                        │\n│   store · recall · find_related · contradictions…   │\n└─────────────────────────┬───────────────────────────┘\n                          │\n┌─────────────────────────▼───────────────────────────┐\n│                Memory Engine                        │\n│  ┌──────────────────────────────────────────────┐  │\n│  │           Enrichment Pipeline                │  │\n│  │  entity extraction → relationship mapping    │  │\n│  │  → semantic embeddings → contradiction check │  │\n│  └──────────────────────────────────────────────┘  │\n└──────────────────┬──────────────────────────────────┘\n                   │\n       ┌───────────┴───────────┐\n       │                       │\n┌──────▼──────┐       ┌────────▼────────┐\n│   SQLite    │       │  PostgreSQL     │\n│  FTS5 index │       │  + pgvector     │\n│  (default)  │       │  (scale-out)    │\n└─────────────┘       └─────────────────┘\n```\n\n---\n\n## Features\n\n**Runs entirely offline**\n- Ollama runs locally — default setup never makes an external network call\n- SQLite database is a single file you own: `~/.memento/memento.db`\n- Swap to OpenAI or Anthropic when you want stronger extraction — opt-in only\n\n**Hybrid search**\n- FTS5 full-text + semantic vector search fused with Reciprocal Rank Fusion (RRF)\n- Finds what you mean, not just what you typed\n\n**Knowledge graph**\n- Extracts 22 entity types: people, projects, tools, languages, APIs, databases, concepts, and more\n- Maps 44 relationship types with confidence scores\n- Interactive graph explorer in the web UI\n\n**Memory lifecycle**\n- Lifecycle states: `planning → active → paused | blocked | completed | cancelled → archived`\n- Decay scoring — stale context loses ranking weight naturally\n- Access-frequency boosting — memories you recall often stay prominent\n\n**Production-ready backends**\n- SQLite (zero deps, CGo-free) for personal/local use\n- PostgreSQL + pgvector + ivfflat index for team or production deployments\n\n**Multi-connection isolation**\n- Separate memory namespaces per project, client, or workspace\n- Route MCP calls to different connections with a single env var\n\n**Web UI**\n- Dashboard with live enrichment queue, entity browser, relationship explorer, graph visualizer\n- One-click integration setup for every supported client\n- Connection testing, CLAUDE.md generation, Cursor Rules download\n- Tracks unrecognized LLM entity types so you can expand your taxonomy over time\n\n---\n\n## LLM Providers\n\n| Provider | Setup | Use when |\n|---|---|---|\n| **Ollama** (default) | `docker compose up` — automatic | Privacy first, no API costs, fully offline |\n| **OpenAI** | Set `MEMENTO_LLM_PROVIDER=openai` + API key | Stronger extraction quality, cloud OK |\n| **Anthropic** | Set `MEMENTO_LLM_PROVIDER=anthropic` + API key | Strongest reasoning, cloud OK |\n\nSwitch providers per connection — different projects can use different LLMs.\n\n---\n\n## Configuration\n\n| Variable | Default | Description |\n|---|---|---|\n| `MEMENTO_PORT` | `6363` | Web UI and REST API port |\n| `MEMENTO_STORAGE_ENGINE` | `sqlite` | `sqlite` or `postgres` |\n| `MEMENTO_DATA_PATH` | `./data` | SQLite database directory |\n| `MEMENTO_LLM_PROVIDER` | `ollama` | `ollama`, `openai`, or `anthropic` |\n| `MEMENTO_OLLAMA_URL` | `http://localhost:11434` | Ollama API endpoint |\n| `MEMENTO_OLLAMA_MODEL` | `qwen2.5:7b` | Extraction model |\n| `MEMENTO_EMBEDDING_MODEL` | `nomic-embed-text` | Embedding model |\n| `MEMENTO_OPENAI_API_KEY` | — | OpenAI API key |\n| `MEMENTO_ANTHROPIC_API_KEY` | — | Anthropic API key |\n| `MEMENTO_DEFAULT_CONNECTION` | — | Default connection name for multi-workspace isolation |\n| `MEMENTO_CONNECTIONS_CONFIG` | — | Path to `connections.json` for multi-workspace setup |\n| `MEMENTO_BACKUP_ENABLED` | `false` | Automated backups |\n| `MEMENTO_BACKUP_INTERVAL` | `24h` | Backup frequency |\n\n### PostgreSQL\n\n```bash\ndocker compose --profile postgres up -d\n```\n\n```bash\nMEMENTO_STORAGE_ENGINE=postgres\nMEMENTO_DATABASE_URL=postgres://memento:memento_dev_password@localhost:5433/memento\n```\n\n---\n\n## Project Structure\n\n```\nmemento/\n├── cmd/\n│   ├── memento-mcp/        # MCP server binary — connect this to your AI client\n│   ├── memento-web/        # Web dashboard — entity browser, graph explorer, settings\n│   └── memento-setup/      # Interactive setup wizard\n├── internal/\n│   ├── api/mcp/            # MCP JSON-RPC server — 20 tool handlers\n│   ├── engine/             # Memory engine, enrichment pipeline, async workers\n│   ├── llm/                # Ollama, OpenAI, Anthropic + circuit breaker\n│   └── storage/\n│       ├── sqlite/         # SQLite with FTS5 and hybrid vector search\n│       └── postgres/       # PostgreSQL with pgvector and ivfflat index\n├── web/\n│   ├── handlers/           # HTMX handlers\n│   ├── templates/          # Dashboard, graph, entities, settings, integrations\n│   └── static/templates/   # MCP config snippets generated per client\n├── docs/\n│   └── integrations/       # Per-client integration guides\n├── migrations/             # SQL schema migrations\n└── docker-compose.yml\n```\n\n---\n\n## Contributing\n\nIssues and PRs welcome. Open an issue before starting significant work.\n\n```bash\ngo test ./...\n\ngo build -o memento-mcp ./cmd/memento-mcp/\ngo build -o memento-web ./cmd/memento-web/\ngo build -o memento-setup ./cmd/memento-setup/\n```\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n## Built by\n\n**[MJ Bonanno](https://mjbonanno.com)** — software architect and founder of **[Scrypster](https://scrypster.com)**.\n\n---\n\n*Remember everything. Forget nothing.*\n*Unlike Leonard Shelby, your context is here to stay — searchable, versioned, and backed by a knowledge graph that never fades.*\n",
  "bytes": 16139,
  "sha": "bd583e61c42506e7f4c73c5c9e54bc856acfa885c0caa55057add9aa9ebe1b1f",
  "repo_slug": "scrypster/memento",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_scrypster_memento_b9799d27/readme"
}