{"id":50916153,"url":"https://github.com/jnmetacode/engram","last_synced_at":"2026-06-16T15:02:27.588Z","repository":{"id":363790870,"uuid":"1264461565","full_name":"jnMetaCode/engram","owner":"jnMetaCode","description":"engram — your local, private memory layer. Index notes, PDFs \u0026 docs, then recall anything with citations + temporal reasoning. 100% local, zero deps, MCP-native.","archived":false,"fork":false,"pushed_at":"2026-06-10T11:42:40.000Z","size":51,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T12:03:56.468Z","etag":null,"topics":["agent-memory","agents","ai","cli","local-first","mcp","memory","ollama","privacy","rag","second-brain","semantic-search"],"latest_commit_sha":null,"homepage":"https://github.com/jnMetaCode/local-agent-toolkit","language":"JavaScript","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/jnMetaCode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-06-09T22:53:32.000Z","updated_at":"2026-06-10T11:42:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jnMetaCode/engram","commit_stats":null,"previous_names":["jnmetacode/engram"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jnMetaCode/engram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnMetaCode%2Fengram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnMetaCode%2Fengram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnMetaCode%2Fengram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnMetaCode%2Fengram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jnMetaCode","download_url":"https://codeload.github.com/jnMetaCode/engram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnMetaCode%2Fengram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34410784,"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-06-16T02:00:06.860Z","response_time":126,"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-memory","agents","ai","cli","local-first","mcp","memory","ollama","privacy","rag","second-brain","semantic-search"],"created_at":"2026-06-16T15:02:26.553Z","updated_at":"2026-06-16T15:02:27.582Z","avatar_url":"https://github.com/jnMetaCode.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🧠 engram\n\n### Your local, private memory layer\n\n**Index your notes and files, then recall anything — with citations and a sense of time. 100% on your machine.**\nNo cloud. No account. No data leaving your laptop. Just `npx @jnmetacode/engram`.\n\n```bash\nnpx @jnmetacode/engram ingest ~/notes\nnpx @jnmetacode/engram recall \"what did I decide about pricing\"\n```\n\nEnglish | [简体中文](https://github.com/jnMetaCode/engram/blob/main/README.zh-CN.md)\n\n![engram demo — ingest, cited recall, time filters, and self-improving reinforce](https://raw.githubusercontent.com/jnMetaCode/engram/main/docs/demo.gif)\n\n\u003c/div\u003e\n\n---\n\nYour notes, journals, and docs are a second brain you can't query. Hosted \"AI\nmemory\" tools want you to upload all of it to their cloud. engram is the\nopposite: it builds a searchable memory **on your machine** and never phones home.\n\n```bash\nnpx @jnmetacode/engram ingest ~/notes ~/journal     # index markdown, text, PDF, HTML …\nnpx @jnmetacode/engram recall \"auth bug clock skew\" # ranked passages, with citations\nnpx @jnmetacode/engram recall \"hiring\" --since week  # time-aware: only recent memories\nnpx @jnmetacode/engram ask \"summarize my pricing decisions\"   # (optional) local LLM answer\n```\n\nEvery result tells you exactly where it came from — `file:line` and the date —\nso you can trust it and jump to the source.\n\n\u003e **Supported files:** Markdown, text, `org`, `rst`, **PDF**, **HTML**, and\n\u003e **EPUB** — all via zero-dependency extractors. PDF/EPUB extraction is\n\u003e best-effort: text-based files work great; scanned (image-only), encrypted, or\n\u003e custom-CID-font PDFs and DRM'd EPUBs may extract poorly.\n\n## Why engram\n\n- **Local-first \u0026 private.** Memory lives in one JSON file on disk. Embeddings and\n  answers (optional) run through a **local Ollama** — nothing ever leaves your box.\n- **Temporal reasoning, not a flat vector dump.** Every memory carries a\n  timestamp (file mtime *and* dates found in the text). Recall is recency-aware\n  and supports `--since week`, `--since 2026-05-01`, etc. — so \"what was I working\n  on lately\" actually works.\n- **Cited recall.** Results come back as `source:line (date)` with a snippet.\n- **Works with zero setup.** A built-in BM25 lexical engine means recall works\n  offline with no model at all. Add a local embedding model for semantic recall\n  when you want it — it's an enhancement, never a requirement.\n- **Zero dependencies.** Pure Node built-ins. A few hundred readable lines.\n- **A memory backend for your agents, too.** `engram serve` exposes a tiny local\n  API (`/remember`, `/recall`) so your AI agents get private, persistent memory.\n\n## Install \u0026 use\n\n```bash\n# index some notes (markdown, txt, org, rst …)\nnpx @jnmetacode/engram ingest ~/Documents/notes\n\n# …or keep it live — re-indexes automatically as you edit\nnpx @jnmetacode/engram watch ~/Documents/notes\n\n# recall — lexical + temporal, fully offline\nnpx @jnmetacode/engram recall \"postgres migration plan\"\nnpx @jnmetacode/engram recall \"standup notes\" --since 7d --limit 5\n\n# optional: semantic recall + answers via a LOCAL Ollama\nnpx @jnmetacode/engram ingest ~/notes --embed           # one-time, computes embeddings\nnpx @jnmetacode/engram recall \"that idea about caching\" --semantic\nnpx @jnmetacode/engram ask \"what are my open questions about auth?\"\n\n# housekeeping\nnpx @jnmetacode/engram status\nnpx @jnmetacode/engram forget old-project\n```\n\n\u003e **New here?** [`examples/`](examples/) has three sample notes and a 30-second\n\u003e walkthrough you can run against this repo — ingest → recall → temporal filter.\n\n## How it works\n\n```\n  files ──chunk──▶ memory store (one local JSON file)\n                      │   each chunk: text · source:line · timestamp · term-freqs · [embedding]\n  recall(query) ─────┤\n                      ├─ BM25 lexical score        (always on, offline)\n                      ├─ semantic cosine           (optional, local Ollama)\n                      └─ temporal recency + filter (the part most tools miss)\n                          → ranked, cited passages\n```\n\nThe store is a plain JSON file (default `~/.engram/store.json`). Back it up,\ninspect it, delete it — it's yours.\n\n## Memory for agents\n\n```bash\nnpx @jnmetacode/engram serve            # http://127.0.0.1:7077 (local only)\n```\n\n```bash\ncurl -s localhost:7077/remember -d '{\"text\":\"Ship date is 2026-07-01\"}'\ncurl -s localhost:7077/recall   -d '{\"query\":\"ship date\"}'\n```\n\nThe open, local alternative to a hosted agent-memory service. Point your agent at\nit and its memories stay on your machine, with the same temporal ranking.\n\n### Use it as an MCP server (Claude, etc.)\n\nengram speaks the [Model Context Protocol](https://modelcontextprotocol.io) over\nstdio, so Claude Desktop / Claude Code can use your memory as a tool — `engram_recall`,\n`engram_remember`, `engram_reinforce`, `engram_status`. Add to `claude_desktop_config.json` (or a\nproject `.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"engram\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jnmetacode/engram\", \"mcp\"]\n    }\n  }\n}\n```\n\n\nWorks in **any MCP client** — same JSON, different config file:\n\n| Client | Where the config lives |\n| --- | --- |\n| Claude Desktop | `claude_desktop_config.json` |\n| Claude Code | project `.mcp.json` (or the plugin: `/plugin marketplace add jnMetaCode/local-agent-toolkit`) |\n| Cursor | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` |\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` |\n| Cline | `cline_mcp_settings.json` |\n| Zed | `settings.json` → `context_servers` |\n\n(Check your client's MCP docs for the exact key names — the `command`/`args` pair above is the same everywhere.)\n\nNow the model can recall your notes and persist new memories mid-conversation —\nall locally. Zero dependencies, no SDK: it's a few hundred lines of pure Node\nimplementing JSON-RPC over stdio (spec revision 2025-06-18).\n\n## Self-improving recall (`reinforce`)\n\nRecall gets better the more you use it. When a recall surfaces the right\nanswer, say so:\n\n```bash\nnpx @jnmetacode/engram recall \"staging deploy fails\"\nnpx @jnmetacode/engram reinforce \"staging deploy fails\" deploy-notes.md\n```\n\nengram records \"queries like this are answered by that source\" (plain,\ninspectable data in your store file) and gives the source a **bounded** boost\non similar future queries. It re-orders relevant results only — it can never\nresurrect a non-matching one — and `forget` drops a source's feedback with it.\nAgents can do this for themselves via the `engram_reinforce` MCP tool: verify\nan answer, reinforce it, and the shared memory gets sharper with every task\n(see the [`self-evolve` skill](https://github.com/jnMetaCode/skillet/tree/main/skills/self-evolve)).\n\n## Optional: local embeddings (Ollama)\n\nengram never ships your data anywhere. For semantic recall it talks to a **local**\n[Ollama](https://ollama.com):\n\n```bash\nollama pull nomic-embed-text     # embeddings\nollama pull llama3.2             # for `engram ask`\n```\n\nWithout Ollama, engram still works great in lexical + temporal mode.\n\n## Commands\n\n| | |\n| --- | --- |\n| `engram ingest \u003cpath...\u003e` | index files/folders (`--embed` for semantic) |\n| `engram watch \u003cpath...\u003e` | index, then auto-reindex on change (live memory) |\n| `engram recall \u003cquery\u003e` | cited passages (`--since`, `--until`, `--limit`, `--semantic`) |\n| `engram ask \u003cquery\u003e` | compose an answer from memory (needs Ollama) |\n| `engram reinforce \"\u003cq\u003e\" \u003csrc\u003e` | self-improving recall: confirm which source answered a query |\n| `engram status` | what's stored |\n| `engram forget \u003csubstr\u003e` | remove memories by source |\n| `engram serve` | local memory API (HTTP) for agents |\n| `engram mcp` | run as an MCP server (stdio) for Claude/agents |\n\n## Status\n\nEarly MVP. Lexical + temporal recall, citations, ingest/forget, incremental\nre-index, **live `watch` mode** (auto-reindex on change), the local agent API, an\n**MCP server** (stdio), **PDF + HTML + EPUB ingestion** (zero-dep extractors),\nand optional Ollama embeddings/answers all work today. Roadmap: a SQLite store\nfor large vaults.\nStar/watch to follow along.\n\n## Sibling projects\n\nPart of a small, local-first, zero-dependency toolkit for building AI agents — see the [toolkit overview \u0026 end-to-end recipe](https://github.com/jnMetaCode/local-agent-toolkit):\n\n- 🧠 **engram** — a local, private memory layer for agents (and you) *(this repo)*\n- 🍳 **[skillet](https://github.com/jnMetaCode/skillet)** — a package manager for agent skills\n- 🔭 **[tracelet](https://github.com/jnMetaCode/tracelet)** — local DevTools to debug agent runs\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjnmetacode%2Fengram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjnmetacode%2Fengram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjnmetacode%2Fengram/lists"}