{"id":49156985,"url":"https://github.com/Gentleman-Programming/engram","last_synced_at":"2026-04-28T18:01:00.531Z","repository":{"id":338819534,"uuid":"1159234860","full_name":"Gentleman-Programming/engram","owner":"Gentleman-Programming","description":"Persistent memory system for AI coding agents. Agent-agnostic Go binary with SQLite + FTS5, MCP server, HTTP API, CLI, and TUI.","archived":false,"fork":false,"pushed_at":"2026-04-26T15:19:51.000Z","size":22238,"stargazers_count":2842,"open_issues_count":96,"forks_count":310,"subscribers_count":33,"default_branch":"main","last_synced_at":"2026-04-26T17:27:49.544Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/Gentleman-Programming.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-16T13:38:41.000Z","updated_at":"2026-04-26T15:57:32.000Z","dependencies_parsed_at":"2026-02-28T03:05:36.668Z","dependency_job_id":null,"html_url":"https://github.com/Gentleman-Programming/engram","commit_stats":null,"previous_names":["gentleman-programming/engram"],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/Gentleman-Programming/engram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gentleman-Programming%2Fengram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gentleman-Programming%2Fengram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gentleman-Programming%2Fengram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gentleman-Programming%2Fengram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Gentleman-Programming","download_url":"https://codeload.github.com/Gentleman-Programming/engram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gentleman-Programming%2Fengram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32392304,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T14:34:11.604Z","status":"ssl_error","status_checked_at":"2026-04-28T14:32:37.009Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-04-22T10:00:23.575Z","updated_at":"2026-04-28T18:01:00.525Z","avatar_url":"https://github.com/Gentleman-Programming.png","language":"Go","funding_links":[],"categories":["Go","Design Primitives","others","MCP Servers \u0026 Protocol","MCP Ecosystem"],"sub_categories":["Memory \u0026 State","Servers"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"1024\" alt=\"Engram Cloud\" src=\"assets/branding/engram-cloud-logo.png\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003ePersistent memory for AI coding agents\u003c/strong\u003e\u003cbr\u003e\n  \u003cem\u003eAgent-agnostic. Single binary. Zero dependencies.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"docs/INSTALLATION.md\"\u003eInstallation\u003c/a\u003e \u0026bull;\n  \u003ca href=\"docs/engram-cloud/README.md\"\u003eEngram Cloud\u003c/a\u003e \u0026bull;\n  \u003ca href=\"docs/AGENT-SETUP.md\"\u003eAgent Setup\u003c/a\u003e \u0026bull;\n  \u003ca href=\"docs/ARCHITECTURE.md\"\u003eArchitecture\u003c/a\u003e \u0026bull;\n  \u003ca href=\"docs/PLUGINS.md\"\u003ePlugins\u003c/a\u003e \u0026bull;\n  \u003ca href=\"CONTRIBUTING.md\"\u003eContributing\u003c/a\u003e \u0026bull;\n  \u003ca href=\"DOCS.md\"\u003eFull Docs\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003e **engram** `/ˈen.ɡræm/` — *neuroscience*: the physical trace of a memory in the brain.\n\nYour AI coding agent forgets everything when the session ends. Engram gives it a brain.\n\nA **Go binary** with SQLite + FTS5 full-text search, exposed via CLI, HTTP API, MCP server, and an interactive TUI. Works with **any agent** that supports MCP — Claude Code, OpenCode, Gemini CLI, Codex, VS Code (Copilot), Antigravity, Cursor, Windsurf, or anything else.\n\n```\nAgent (Claude Code / OpenCode / Gemini CLI / Codex / VS Code / Antigravity / ...)\n    ↓ MCP stdio\nEngram (single Go binary)\n    ↓\nSQLite + FTS5 (~/.engram/engram.db)\n```\n\n## Quick Start\n\n### Install\n\n```bash\nbrew install gentleman-programming/tap/engram\n```\n\nWindows, Linux, and other install methods → [docs/INSTALLATION.md](docs/INSTALLATION.md)\n\n### Setup Your Agent\n\n| Agent | One-liner |\n|-------|-----------|\n| Claude Code | `claude plugin marketplace add Gentleman-Programming/engram \u0026\u0026 claude plugin install engram` |\n| OpenCode | `engram setup opencode` |\n| Gemini CLI | `engram setup gemini-cli` |\n| Codex | `engram setup codex` |\n| VS Code | `code --add-mcp '{\"name\":\"engram\",\"command\":\"engram\",\"args\":[\"mcp\"]}'` |\n| Cursor / Windsurf / Any MCP | See [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md) |\n\nFull per-agent config, Memory Protocol, and compaction survival → [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md)\n\nThat's it. No Node.js, no Python, no Docker. **One binary, one SQLite file.**\n\n## How It Works\n\n```\n1. Agent completes significant work (bugfix, architecture decision, etc.)\n2. Agent calls mem_save → title, type, What/Why/Where/Learned\n3. Engram persists to SQLite with FTS5 indexing\n4. Next session: agent searches memory, gets relevant context\n```\n\nFull details on session lifecycle, topic keys, and memory hygiene → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)\n\n## MCP Tools (17)\n\n| Category | Tools |\n|----------|-------|\n| **Save \u0026 Update** | `mem_save`, `mem_update`, `mem_delete`, `mem_suggest_topic_key` |\n| **Search \u0026 Retrieve** | `mem_search`, `mem_context`, `mem_timeline`, `mem_get_observation` |\n| **Session Lifecycle** | `mem_session_start`, `mem_session_end`, `mem_session_summary` |\n| **Conflict Surfacing** | `mem_judge` |\n| **Utilities** | `mem_save_prompt`, `mem_stats`, `mem_capture_passive`, `mem_merge_projects`, `mem_current_project` |\n\nFull tool reference with parameters → [DOCS.md#mcp-tools-17-tools](DOCS.md#mcp-tools-17-tools)\n\n## Terminal UI\n\n```bash\nengram tui\n```\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"assets/tui-dashboard.png\" alt=\"TUI Dashboard\" width=\"400\" /\u003e\n  \u003cimg width=\"400\" alt=\"image\" src=\"https://github.com/user-attachments/assets/0308991a-58bb-4ad8-9aa2-201c059f8b64\" /\u003e\n  \u003cimg src=\"assets/tui-detail.png\" alt=\"TUI Observation Detail\" width=\"400\" /\u003e\n  \u003cimg src=\"assets/tui-search.png\" alt=\"TUI Search Results\" width=\"400\" /\u003e\n\u003c/p\u003e\n\n**Navigation**: `j/k` vim keys, `Enter` to drill in, `/` to search, `Esc` back. Catppuccin Mocha theme.\n\n## Git Sync\n\nShare memories across machines. Uses compressed chunks — no merge conflicts, no huge files.\n\nLocal SQLite remains the source of truth. Cloud integration is opt-in replication.\n\n```bash\nengram sync                    # Export new memories as compressed chunk\ngit add .engram/ \u0026\u0026 git commit -m \"sync engram memories\"\nengram sync --import           # On another machine: import new chunks\nengram sync --status           # Check sync status\n```\n\nFull sync documentation → [DOCS.md](DOCS.md)\n\n## Cloud Integration (Opt-In Replication)\n\nCloud is optional. Local SQLite stays authoritative; cloud is replication/shared access only.\n\n**Recommended first path (local smoke):**\n\n```bash\ndocker compose -f docker-compose.cloud.yml up -d\nengram cloud config --server http://127.0.0.1:18080\nengram cloud enroll smoke-project\nengram sync --cloud --project smoke-project\n```\n\nCloud mode is always project-scoped (`--project` is required; `engram sync --cloud --all` is intentionally blocked).\nKnown repairable cloud sync/upsert/canonicalization failures keep the original error visible and recommend the explicit `doctor`/`repair` flow below; Engram never auto-applies repair from sync or autosync.\n\n**After upgrading `engram` while an MCP client is already running:**\n\n```bash\nengram setup claude-code\n```\n\nThen restart Claude Code so it reloads the Engram MCP subprocess and refreshed hook/config files. Updating the `engram` binary on disk does not replace an already-running stdio MCP process.\n\n**Upgrade flow for existing local databases** (diagnose → repair → bootstrap → status):\n\n```bash\nengram cloud upgrade doctor --project smoke-project        # read-only readiness check\nengram cloud upgrade repair --project smoke-project --dry-run\nengram cloud upgrade repair --project smoke-project --apply\nengram cloud upgrade bootstrap --project smoke-project     # resumable enroll + push + verify\nengram cloud upgrade status --project smoke-project        # stage/class/reason\n```\n\nSee [DOCS.md — Cloud upgrade flow](DOCS.md#cloud-upgrade-flow) for the full state machine.\n\nFor authenticated mode, upgrade flow, dashboard behavior, reason codes, and full runtime/env details:\n\n- [Engram Cloud docs landing](docs/engram-cloud/README.md)\n- [Engram Cloud quickstart](docs/engram-cloud/quickstart.md)\n- [DOCS.md — Cloud CLI reference](DOCS.md#cloud-cli-opt-in)\n- [DOCS.md — Cloud Autosync](DOCS.md#cloud-autosync)\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `engram setup [agent]` | Install agent integration |\n| `engram serve [port]` | Start HTTP API (default: 7437) |\n| `engram mcp [--tools=PROFILE]` | Start MCP server (stdio transport) |\n| `engram tui` | Launch terminal UI |\n| `engram search \u003cquery\u003e` | Search memories |\n| `engram save \u003ctitle\u003e \u003cmsg\u003e` | Save a memory |\n| `engram timeline \u003cobs_id\u003e` | Chronological context |\n| `engram context [project]` | Recent session context |\n| `engram stats` | Memory statistics |\n| `engram export [file]` | Export to JSON |\n| `engram import \u003cfile\u003e` | Import from JSON |\n| `engram sync` | Git sync export/import |\n| `engram cloud \u003csubcommand\u003e` | Opt-in cloud config/status/enrollment + cloud runtime (`serve`) |\n| `engram projects list\\|consolidate\\|prune` | Manage project names |\n| `engram obsidian-export` | Export to Obsidian vault (beta) |\n| `engram version` | Show version |\n\nFull CLI with all flags → [docs/ARCHITECTURE.md#cli-reference](docs/ARCHITECTURE.md#cli-reference)\n\n## Documentation\n\n| Doc | Description |\n|-----|-------------|\n| [Installation](docs/INSTALLATION.md) | All install methods + platform support |\n| [Engram Cloud](docs/engram-cloud/README.md) | Cloud landing page, quickstart, branding, and deep links |\n| [Agent Setup](docs/AGENT-SETUP.md) | Per-agent configuration + Memory Protocol |\n| [Architecture](docs/ARCHITECTURE.md) | How it works + MCP tools + project structure |\n| [Plugins](docs/PLUGINS.md) | OpenCode \u0026 Claude Code plugin details |\n| [Comparison](docs/COMPARISON.md) | Why Engram vs claude-mem |\n| [Intended Usage](docs/intended-usage.md) | Mental model — how Engram is meant to be used |\n| [Obsidian Brain](docs/beta/obsidian-brain.md) | Export memories as Obsidian knowledge graph (beta) |\n| [Contributing](CONTRIBUTING.md) | Contribution workflow + standards |\n| [Full Docs](DOCS.md) | Complete technical reference |\n\n\u003e **Dashboard contributors**: if you modify `.templ` files in `internal/cloud/dashboard/`, run `make templ` to regenerate before committing. See [DOCS.md — Dashboard templ regeneration](DOCS.md#dashboard-templ-regeneration).\n\n## License\n\nMIT\n\n---\n\n**Inspired by [claude-mem](https://github.com/thedotmack/claude-mem)** — but agent-agnostic, simpler, and built different.\n\n## Contributors\n\n\u003ca href=\"https://github.com/Gentleman-Programming/engram/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=Gentleman-Programming/engram\u0026max=100\" /\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGentleman-Programming%2Fengram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGentleman-Programming%2Fengram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGentleman-Programming%2Fengram/lists"}