https://github.com/jnmetacode/engram
engram โ your local, private memory layer. Index notes, PDFs & docs, then recall anything with citations + temporal reasoning. 100% local, zero deps, MCP-native.
https://github.com/jnmetacode/engram
agent-memory agents ai cli local-first mcp memory ollama privacy rag second-brain semantic-search
Last synced: 16 days ago
JSON representation
engram โ your local, private memory layer. Index notes, PDFs & docs, then recall anything with citations + temporal reasoning. 100% local, zero deps, MCP-native.
- Host: GitHub
- URL: https://github.com/jnmetacode/engram
- Owner: jnMetaCode
- License: mit
- Created: 2026-06-09T22:53:32.000Z (23 days ago)
- Default Branch: main
- Last Pushed: 2026-06-10T11:42:40.000Z (22 days ago)
- Last Synced: 2026-06-10T12:03:56.468Z (22 days ago)
- Topics: agent-memory, agents, ai, cli, local-first, mcp, memory, ollama, privacy, rag, second-brain, semantic-search
- Language: JavaScript
- Homepage: https://github.com/jnMetaCode/local-agent-toolkit
- Size: 49.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# ๐ง engram
### Your local, private memory layer
**Index your notes and files, then recall anything โ with citations and a sense of time. 100% on your machine.**
No cloud. No account. No data leaving your laptop. Just `npx @jnmetacode/engram`.
```bash
npx @jnmetacode/engram ingest ~/notes
npx @jnmetacode/engram recall "what did I decide about pricing"
```
English | [็ฎไฝไธญๆ](https://github.com/jnMetaCode/engram/blob/main/README.zh-CN.md)
---
Your notes, journals, and docs are a second brain you can't query. Hosted "AI
memory" tools want you to upload all of it to their cloud. engram is the
opposite: it builds a searchable memory **on your machine** and never phones home.
```bash
npx @jnmetacode/engram ingest ~/notes ~/journal # index markdown, text, PDF, HTML โฆ
npx @jnmetacode/engram recall "auth bug clock skew" # ranked passages, with citations
npx @jnmetacode/engram recall "hiring" --since week # time-aware: only recent memories
npx @jnmetacode/engram ask "summarize my pricing decisions" # (optional) local LLM answer
```
Every result tells you exactly where it came from โ `file:line` and the date โ
so you can trust it and jump to the source.
> **Supported files:** Markdown, text, `org`, `rst`, **PDF**, **HTML**, and
> **EPUB** โ all via zero-dependency extractors. PDF/EPUB extraction is
> best-effort: text-based files work great; scanned (image-only), encrypted, or
> custom-CID-font PDFs and DRM'd EPUBs may extract poorly.
## Why engram
- **Local-first & private.** Memory lives in one JSON file on disk. Embeddings and
answers (optional) run through a **local Ollama** โ nothing ever leaves your box.
- **Temporal reasoning, not a flat vector dump.** Every memory carries a
timestamp (file mtime *and* dates found in the text). Recall is recency-aware
and supports `--since week`, `--since 2026-05-01`, etc. โ so "what was I working
on lately" actually works.
- **Cited recall.** Results come back as `source:line (date)` with a snippet.
- **Works with zero setup.** A built-in BM25 lexical engine means recall works
offline with no model at all. Add a local embedding model for semantic recall
when you want it โ it's an enhancement, never a requirement.
- **Zero dependencies.** Pure Node built-ins. A few hundred readable lines.
- **A memory backend for your agents, too.** `engram serve` exposes a tiny local
API (`/remember`, `/recall`) so your AI agents get private, persistent memory.
## Install & use
```bash
# index some notes (markdown, txt, org, rst โฆ)
npx @jnmetacode/engram ingest ~/Documents/notes
# โฆor keep it live โ re-indexes automatically as you edit
npx @jnmetacode/engram watch ~/Documents/notes
# recall โ lexical + temporal, fully offline
npx @jnmetacode/engram recall "postgres migration plan"
npx @jnmetacode/engram recall "standup notes" --since 7d --limit 5
# optional: semantic recall + answers via a LOCAL Ollama
npx @jnmetacode/engram ingest ~/notes --embed # one-time, computes embeddings
npx @jnmetacode/engram recall "that idea about caching" --semantic
npx @jnmetacode/engram ask "what are my open questions about auth?"
# housekeeping
npx @jnmetacode/engram status
npx @jnmetacode/engram forget old-project
```
> **New here?** [`examples/`](examples/) has three sample notes and a 30-second
> walkthrough you can run against this repo โ ingest โ recall โ temporal filter.
## How it works
```
files โโchunkโโโถ memory store (one local JSON file)
โ each chunk: text ยท source:line ยท timestamp ยท term-freqs ยท [embedding]
recall(query) โโโโโโค
โโ BM25 lexical score (always on, offline)
โโ semantic cosine (optional, local Ollama)
โโ temporal recency + filter (the part most tools miss)
โ ranked, cited passages
```
The store is a plain JSON file (default `~/.engram/store.json`). Back it up,
inspect it, delete it โ it's yours.
## Memory for agents
```bash
npx @jnmetacode/engram serve # http://127.0.0.1:7077 (local only)
```
```bash
curl -s localhost:7077/remember -d '{"text":"Ship date is 2026-07-01"}'
curl -s localhost:7077/recall -d '{"query":"ship date"}'
```
The open, local alternative to a hosted agent-memory service. Point your agent at
it and its memories stay on your machine, with the same temporal ranking.
### Use it as an MCP server (Claude, etc.)
engram speaks the [Model Context Protocol](https://modelcontextprotocol.io) over
stdio, so Claude Desktop / Claude Code can use your memory as a tool โ `engram_recall`,
`engram_remember`, `engram_reinforce`, `engram_status`. Add to `claude_desktop_config.json` (or a
project `.mcp.json`):
```json
{
"mcpServers": {
"engram": {
"command": "npx",
"args": ["-y", "@jnmetacode/engram", "mcp"]
}
}
}
```
Works in **any MCP client** โ same JSON, different config file:
| Client | Where the config lives |
| --- | --- |
| Claude Desktop | `claude_desktop_config.json` |
| Claude Code | project `.mcp.json` (or the plugin: `/plugin marketplace add jnMetaCode/local-agent-toolkit`) |
| Cursor | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Cline | `cline_mcp_settings.json` |
| Zed | `settings.json` โ `context_servers` |
(Check your client's MCP docs for the exact key names โ the `command`/`args` pair above is the same everywhere.)
Now the model can recall your notes and persist new memories mid-conversation โ
all locally. Zero dependencies, no SDK: it's a few hundred lines of pure Node
implementing JSON-RPC over stdio (spec revision 2025-06-18).
## Self-improving recall (`reinforce`)
Recall gets better the more you use it. When a recall surfaces the right
answer, say so:
```bash
npx @jnmetacode/engram recall "staging deploy fails"
npx @jnmetacode/engram reinforce "staging deploy fails" deploy-notes.md
```
engram records "queries like this are answered by that source" (plain,
inspectable data in your store file) and gives the source a **bounded** boost
on similar future queries. It re-orders relevant results only โ it can never
resurrect a non-matching one โ and `forget` drops a source's feedback with it.
Agents can do this for themselves via the `engram_reinforce` MCP tool: verify
an answer, reinforce it, and the shared memory gets sharper with every task
(see the [`self-evolve` skill](https://github.com/jnMetaCode/skillet/tree/main/skills/self-evolve)).
## Optional: local embeddings (Ollama)
engram never ships your data anywhere. For semantic recall it talks to a **local**
[Ollama](https://ollama.com):
```bash
ollama pull nomic-embed-text # embeddings
ollama pull llama3.2 # for `engram ask`
```
Without Ollama, engram still works great in lexical + temporal mode.
## Commands
| | |
| --- | --- |
| `engram ingest ` | index files/folders (`--embed` for semantic) |
| `engram watch ` | index, then auto-reindex on change (live memory) |
| `engram recall ` | cited passages (`--since`, `--until`, `--limit`, `--semantic`) |
| `engram ask ` | compose an answer from memory (needs Ollama) |
| `engram reinforce "" ` | self-improving recall: confirm which source answered a query |
| `engram status` | what's stored |
| `engram forget ` | remove memories by source |
| `engram serve` | local memory API (HTTP) for agents |
| `engram mcp` | run as an MCP server (stdio) for Claude/agents |
## Status
Early MVP. Lexical + temporal recall, citations, ingest/forget, incremental
re-index, **live `watch` mode** (auto-reindex on change), the local agent API, an
**MCP server** (stdio), **PDF + HTML + EPUB ingestion** (zero-dep extractors),
and optional Ollama embeddings/answers all work today. Roadmap: a SQLite store
for large vaults.
Star/watch to follow along.
## Sibling projects
Part of a small, local-first, zero-dependency toolkit for building AI agents โ see the [toolkit overview & end-to-end recipe](https://github.com/jnMetaCode/local-agent-toolkit):
- ๐ง **engram** โ a local, private memory layer for agents (and you) *(this repo)*
- ๐ณ **[skillet](https://github.com/jnMetaCode/skillet)** โ a package manager for agent skills
- ๐ญ **[tracelet](https://github.com/jnMetaCode/tracelet)** โ local DevTools to debug agent runs
## License
MIT โ see [LICENSE](LICENSE).