{"id":50360002,"url":"https://github.com/samuelngs/mem0-mcp","last_synced_at":"2026-05-30T01:04:22.922Z","repository":{"id":359517145,"uuid":"1246286566","full_name":"samuelngs/mem0-mcp","owner":"samuelngs","description":"MCP bridge and structured memory hooks for self-hosted mem0","archived":false,"fork":false,"pushed_at":"2026-05-22T07:38:00.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-22T15:32:38.680Z","etag":null,"topics":["agent-skills","claude","claude-code","mcp","mem0"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samuelngs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-22T03:44:15.000Z","updated_at":"2026-05-22T07:38:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/samuelngs/mem0-mcp","commit_stats":null,"previous_names":["samuelngs/mem0-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/samuelngs/mem0-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelngs%2Fmem0-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelngs%2Fmem0-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelngs%2Fmem0-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelngs%2Fmem0-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samuelngs","download_url":"https://codeload.github.com/samuelngs/mem0-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelngs%2Fmem0-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33676192,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","claude","claude-code","mcp","mem0"],"created_at":"2026-05-30T01:04:22.144Z","updated_at":"2026-05-30T01:04:22.917Z","avatar_url":"https://github.com/samuelngs.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mem0 Agent Integration\n\nPersistent, structured memory for Claude Code and Codex using self-hosted [mem0](https://github.com/mem0ai/mem0).\n\nThis project provides a shared MCP bridge for the mem0 OSS REST API plus agent-specific hook examples. Claude Code gets the full lifecycle hook protocol. Codex support uses the same MCP bridge and a conservative hook set for the currently verified Codex events.\n\n## What It Does\n\n**MCP Bridge** — A zero-dependency Python stdio server that translates MCP tool calls to the mem0 OSS REST API. It is intended as a self-hosted replacement for the cloud `mcp.mem0.ai` endpoint.\n\n**Lifecycle Hooks** — Shell scripts that inject or remind the agent about a structured memory protocol:\n\n| Hook | Claude Code | Codex | Purpose |\n|------|-------------|-------|---------|\n| `on_session_start.sh` | SessionStart | SessionStart | Bootstrap context from mem0, load anti-patterns |\n| `on_user_prompt.sh` | UserPromptSubmit | UserPromptSubmit | Inject retrieval/save protocol, debounced |\n| `on_stop.sh` | Stop | Stop | Structured outcome save + gap detection |\n| `on_post_research.sh` | PostToolUse | Not installed by default | Remind to save research after Agent/WebSearch |\n| `block_memory_write.sh` | PreToolUse | Not installed by default | Block writes to MEMORY.md, redirect to mem0 |\n| `on_pre_compact.sh` | PreCompact | Not installed by default | Force full context dump before compaction |\n| `on_task_completed.sh` | TaskCompleted | Not installed by default | Extract learnings from completed tasks |\n\nCodex may support additional hook events in future versions; the installer only configures the events verified in current local Codex builds.\n\n## Memory Types\n\nThe hooks enforce 8 structured memory types:\n\n| Type | When to Save | What to Include |\n|------|-------------|-----------------|\n| `research` | After code exploration or web search | Key findings, sources, relevant code |\n| `problem` | When a problem is identified | Error messages, symptoms, repro steps |\n| `solution` | When proposing a fix | Approach chosen, WHY, alternatives considered |\n| `plan` | When creating implementation steps | Ordered steps, dependencies, risks |\n| `progress` | After each major step | What's done, what's next, blockers |\n| `pivot` | When changing approach | What changed, WHY previous approach failed |\n| `outcome` | When work is completed | Files changed, verification, open items |\n| `anti_pattern` | When an approach fails | What was tried, exact failure, WHY it broke |\n\n**Key enforcement:** the agent must search for `anti_pattern` memories before proposing a fix or solution.\n\n## Prerequisites\n\n- Self-hosted [mem0](https://github.com/mem0ai/mem0) server, OSS version\n- Python 3.8+\n- jq\n- At least one supported agent CLI:\n  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)\n  - Codex CLI\n\n## Quick Install\n\n```bash\ngit clone https://github.com/samuelngs/mem0-mcp.git\ncd mem0-mcp\n\nexport MEM0_BASE_URL=https://mem0.example.com\nexport MEM0_API_KEY=your-api-key\n\n./install.sh\n```\n\nBy default, `./install.sh` uses `--target auto` and installs for whichever supported CLIs are available.\n\nTarget one or both agents explicitly:\n\n```bash\n./install.sh --target claude\n./install.sh --target codex\n./install.sh --target both\n```\n\nThe installer will:\n\n1. Copy files to `~/.mem0/`\n2. Register the mem0 MCP server with Claude Code and/or Codex\n3. Merge agent-specific hooks into the right settings file\n4. Test connectivity to your mem0 server\n\n## Manual Install\n\n### 1. Copy files\n\n```bash\nmkdir -p ~/.mem0/hooks\ncp mcp_bridge.py ~/.mem0/\ncp hooks/*.sh ~/.mem0/hooks/\nchmod +x ~/.mem0/hooks/*.sh\n```\n\n### 2. Register MCP\n\nFor Claude Code:\n\n```bash\nclaude mcp add mem0 --scope user \\\n  -e MEM0_BASE_URL=https://mem0.example.com \\\n  -e MEM0_API_KEY=your-api-key \\\n  -- python3 ~/.mem0/mcp_bridge.py\n```\n\nFor Codex:\n\n```bash\ncodex mcp add mem0 \\\n  --env MEM0_BASE_URL=https://mem0.example.com \\\n  --env MEM0_API_KEY=your-api-key \\\n  -- python3 ~/.mem0/mcp_bridge.py\n```\n\n### 3. Add hooks\n\nFor Claude Code, merge the contents of [`examples/claude/hooks.json`](examples/claude/hooks.json) into the `hooks` section of `~/.claude/settings.json`. Preserve any existing hooks.\n\nFor Codex, merge the contents of [`examples/codex/hooks.json`](examples/codex/hooks.json) into `~/.codex/hooks.json`. Preserve any existing hooks.\n\nExample MCP config for Claude Code is available at [`examples/claude/mcp.json`](examples/claude/mcp.json).\n\n### 4. Export env vars\n\nAdd to your shell profile (`~/.zshrc`, `~/.bashrc`):\n\n```bash\nexport MEM0_BASE_URL=https://mem0.example.com\nexport MEM0_API_KEY=your-api-key\n```\n\n### 5. Restart your agent\n\nRestart Claude Code and/or Codex so the MCP server and hooks are loaded.\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `MEM0_BASE_URL` | Yes | URL of your mem0 server |\n| `MEM0_API_KEY` | Yes | API key for authentication |\n| `MEM0_USER_ID` | No | Override auto-detected user ID, defaults to `$USER` |\n| `MEM0_PROJECT_ID` | No | Override auto-detected project ID, defaults to git remote slug |\n| `MEM0_TARGET` | No | Installer target: `auto`, `claude`, `codex`, or `both` |\n\n### Project Mapping\n\nTo override project IDs per directory, create `~/.mem0/project_map.json`:\n\n```json\n{\n  \"/path/to/project-a\": \"my-project-a\",\n  \"/path/to/project-b\": \"my-project-b\"\n}\n```\n\n### Auto-Detection\n\nWithout overrides, identity and project are resolved automatically:\n\n- **User ID**: `MEM0_USER_ID` env var -\u003e `$USER` -\u003e `\"default\"`\n- **Project ID**: `MEM0_PROJECT_ID` env var -\u003e `project_map.json` -\u003e git remote slug (`owner-repo`) -\u003e directory basename\n- **Branch**: `git branch --show-current` -\u003e `\"unknown\"`\n\n## How It Works\n\n### Claude Code Lifecycle\n\n```text\nSessionStart\n  Bootstrap context, inject protocol, reset counters\n\nUserPromptSubmit\n  Inject full or short retrieval/save protocol\n\nPostToolUse\n  Remind to save research findings\n\nPreToolUse\n  Block MEMORY.md writes and track save cadence\n\nPreCompact\n  Force full session state save\n\nStop\n  Request structured outcome save\n\nTaskCompleted\n  Request completed-task learnings\n```\n\n### Codex Lifecycle\n\n```text\nSessionStart\n  Bootstrap context and inject the protocol\n\nUserPromptSubmit\n  Inject full or short retrieval/save protocol\n\nStop\n  Request structured outcome save\n```\n\nCodex still gets the full `mem0` MCP tool set. The difference is hook coverage, not memory capability.\n\n### mem0 OSS API Notes\n\nThis bridge targets the mem0 OSS REST API, not the cloud API:\n\n- No `/v1/` prefix; endpoints are `/memories`, `/search`, `/entities`\n- Auth via `X-API-Key` header\n- Search requires `user_id` inside `filters`, not as a top-level parameter\n- The bridge handles this translation automatically\n\n## Examples Layout\n\n```text\nexamples/\n  claude/\n    hooks.json\n    mcp.json\n  codex/\n    hooks.json\n```\n\n## Uninstall\n\nBy default, `./uninstall.sh` uses `--target auto` and removes whichever Claude/Codex config it finds:\n\n```bash\n./uninstall.sh\n```\n\nTarget one or both agents explicitly:\n\n```bash\n./uninstall.sh --target claude\n./uninstall.sh --target codex\n./uninstall.sh --target both\n```\n\nThe uninstaller removes MCP registration and hooks for the selected agents. It removes `~/.mem0` only when no remaining Claude/Codex hook config references it. Use `--keep-files` to always leave `~/.mem0` in place.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuelngs%2Fmem0-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamuelngs%2Fmem0-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuelngs%2Fmem0-mcp/lists"}