{"slug": "show-hn-scribe-a-cli-that-builds-ai-agent-memory-from-your-repos-and-sessions", "title": "Show HN: Scribe, a CLI that builds AI agent memory from your repos and sessions", "summary": "Scribe, a new open-source CLI tool, automatically builds a cross-project knowledge base for AI coding agents by mining git history, Claude Code and Codex sessions, and self-sent URLs, writing a curated markdown wiki that agents query before acting. It runs entirely locally on Ollama with zero API spend, auto-commits hourly, and supports typed entity relationships to compound knowledge across projects.", "body_md": "### Context-aware agents\n\n`scribe init`\n\nwrites a handshake block into **both** `~/.claude/CLAUDE.md`\n\nand `~/.codex/AGENTS.md`\n\n, so every session in every project queries your KB before recommending a library or proposing an architecture.\n\n**scribe reads your git history, your Claude Code & Codex sessions, and self-sent URLs, then writes the wiki for you** — so the next agent session already knows what you decided and why. It’s memory your agents read before they act, not a second brain you maintain and never reopen: plain markdown in git, cross-project, cron-driven, and able to run **100% locally on Ollama** for zero API spend.\n\n`brew install oliver-kriska/scribe/scribe`\n\nscribe mines four input streams, filters out the noise before any LLM touches it, then fans dense sources into entity-first wiki pages. Every step runs on cron; set it up once and forget it.\n\nGit repos, Claude Code & Codex sessions, URLs you text yourself, and drop files from other projects. scribe auto-discovers every codebase you've ever opened in either CLI and keeps the manifest fresh.\n\nKeyword-density scoring rejects boilerplate sessions before any LLM call, so cheap sessions cost nothing. Survivors go through a two-pass absorb: pass 1 grounds atomic facts, pass 2 fans dense sources into multiple entity-first wiki pages.\n\nAuto-generated wikilinks, backlinks JSON, and retrieval-context paragraphs spliced into every article so embeddings catch implicit entities. `qmd`\n\nreindexes for semantic search, reachable from any terminal, in any directory, or from inside Claude Code via MCP.\n\nscribe isn't RAG, it isn't Obsidian, and it isn't another LLM-on-every-session burner. It sits between them: watches your work, writes the notes for you, and compounds knowledge across every project you touch.\n\n`scribe init`\n\nwrites a handshake block into **both** `~/.claude/CLAUDE.md`\n\nand `~/.codex/AGENTS.md`\n\n, so every session in every project queries your KB before recommending a library or proposing an architecture.\n\nHourly auto-commits. Every 2 hours: project extraction. 3×/day: session mining. Every 30 minutes: queued URLs. Every 4 hours: self-iMessaged links. Sundays at 02:00: the full Dream consolidation, with a lighter hot-domain pass daily in between.\n\nOne cross-project KB, not siloed per repo. Solve the oban idempotency bug in project A on Monday; the agent finds your fix on Friday when the same shape comes up in project B.\n\nPer-project extraction, two-pass absorb, Dream cycle, assess, deep, session-mine, relations migrate: every LLM op runs end-to-end against a local Ollama server. One line in `scribe.yaml`\n\nflips the whole pipeline. **Zero API spend.**\n\nFile over app: the corpus has to outlive the pipeline. A git repo of plain markdown with YAML frontmatter. Push to your own GitHub, Gitea, or Forgejo; open in Obsidian, VS Code, vim, or mdbook. **No SaaS, no vendor lock-in.**\n\nArticles connect via a closed **10-kind** typed-edge schema: `supersedes`\n\n, `contradicts`\n\n, `derived_from`\n\n, `specializes`\n\n, `extends`\n\n, and five more. `scribe relations migrate`\n\nclassifies existing `related:`\n\nlinks into it with an LLM.\n\nThe whole surface, in numbers — every figure is checkable against `scribe --help`\n\nand `scribe.yaml`\n\n, not marketing. Local mode needs no key at all; the default Anthropic path signs in through your `claude -p`\n\nCLI, not an API key.\n\n**scribe is a compiled knowledge base, not a vector database**: it auto-writes a curated markdown wiki your agents query with BM25, so there's nothing to embed and nothing to host. The \"second brain\" debate is about notes *you* read. scribe isn't that. It's memory your *agent* reads before it decides: the reasons behind a choice, not summaries you'll never reopen. It sits between manual-notes tools (Obsidian, Notion) and unbounded LLM-on-every-query approaches (vanilla RAG, claude-memory-compiler): a curated wiki on top of raw sources kept verbatim, small enough for an agent to read whole, and cheap to query because most lookups are plain-text matches, not vector guesses.\n\n| Capability | scribe | RAGLangChain · LlamaIndex | Code Insights@code-insights/cli | AnythingLLM | Obsidian |\n|---|---|---|---|---|---|\n| Auto-written from your dev work | Yes | You index docs | Yes | You upload docs | You type notes |\n| Sources captured | Sessions + git + URLs | Docs you feed | Coding sessions only | Docs you upload | Notes you write |\n| Output is portable markdown in git | Yes | Vector chunks | SQLite dashboard | Vector store | Yes |\n| Vector DB required? | Not needed | Required | Not needed | Required | Not needed |\n| Full-text (BM25) search | qmd · FTS5 | Vector recall only | Dashboard analytics | Vector chat | Yes |\n| Agents read it back before deciding | CLAUDE.md / AGENTS.md | If you wire it | Human dashboard | You chat with it | No |\n| Local-first, no API key (Ollama) | 100% Ollama | Local embeddings | Ollama option | Local LLM + DB | AI add-ons need keys |\n\n| Tool | Session mining | Cron-driven | Density pre-filter | Two-pass absorb | Multi-project | Local-mode |\n|---|---|---|---|---|---|---|\n| scribecurated wiki + raw sources, in git | Claude + Codex | launchd / systemd | BM25 | atomic facts → pass-2 | manifest-tracked | 100% Ollama |\n| claude-memory-compilerAnthropic-only, single project | Claude only · $115 / 20min · issue #3 | manual | none | single-pass | single repo | API only |\n| nvk/llm-wikiLLM-built wiki, no mining | user-fed | manual | none | single-pass | single repo | Ollama possible |\n| basic-memoryMCP memory server | issue #669 since Mar | request-driven | none | single-pass | per-MCP-client | local embeddings |\n| RAG (LangChain, LlamaIndex)retrieve-then-prompt | retrieves chunks | on-query | vector recall | no absorb | per-index | local embeddings |\n| Obsidian / Notionmanual notes tool | you type it | manual | tag-based | no absorb | vault / workspace | Obsidian = local, Notion = cloud |\n\nscribe is the wiki the LLM writes for you, sitting on top of raw sources kept verbatim. RAG retrieves chunks; scribe gives you a curated, named-entity wiki you can also grep. — project README\n\nscribe is single-user by default and stays that way. But a small team on the same codebases can point every machine at one git-backed KB. The obvious fear with sharing agent sessions — a leaked secret, a private client repo, one teammate's config change reaching everyone — is exactly what the gates below are built to stop. Only knowledge you meant to keep crosses into the shared KB.\n\nA trust layer pins the sensitive surface of a shared `scribe.yaml`\n\n: provider, model, ingest paths, and the secret scanner itself. A pushed change that would repoint inference to a new endpoint or drain a new directory into the KB reverts to the last trusted snapshot until a human approves it.\n\nscribe mines session transcripts, which routinely carry API keys and tokens. In team mode a deterministic secret scanner runs in the commit gate and holds flagged credentials back before anything lands in shared git history. No LLM, no network: a regex pass on the commit path.\n\nEvery `scribe sync`\n\npulls, merges, and reindexes *before* it extracts, and a committed ledger keeps two machines from mining the same git revision twice. Your inference bill scales with commits, not with the number of laptops pointed at the KB.\n\nDiscovered projects start pending. `allowed_remotes`\n\nand source filters gate discovery by git-remote identity, and `scribe projects {list,approve,ignore,review}`\n\ncontrols what enters the pipeline, so a side project or a client checkout never lands in the shared KB without an approve.\n\n`scribe promote <article> --to team-kb`\n\ncopies a page from your personal KB into the shared one, provenance recorded. Derived and coordination files are refused as sources, so the team KB fills with what you meant to publish, not your working scratch.\n\nThe weekly Dream consolidation rewrites, merges, and prunes the whole wiki, so exactly one machine should run it. A committed leader lease in the repo elects that machine: no etcd, no lock server, and two laptops never race to rewrite the same wiki at 02:00 Sunday.\n\nRun the whole pipeline on local Ollama for $0, point it at a hosted OpenAI-compatible API (Together, Groq, Fireworks, Hugging Face) when the laptop is running hot, or keep `claude -p`\n\nfor the Anthropic path. The three coexist; pick the trade per op in `scribe.yaml`\n\n, and nothing reaches a paid provider without explicit config. `scribe cost`\n\nthen reconciles every token across providers and KBs, to the cent against the provider's own dashboard.\n\n``` bash\n~ $ scribe cost\n\nscribe cost — last 7 days — 2 KBs (personal-kb, team-kb)\n\n  model                                             calls     ok  cancl  rate  tmout  wallclock   in-tokens  out-tokens      usd\n  ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n  sonnet                                              301    281      0     0      3      6h54m     250,468     789,357   $92.80\n  haiku                                               151    144      0     0      7      2h21m       1,251     551,761   $10.77\n  together/MiniMaxAI/MiniMax-M3                        195    195      0     0      0      1h06m   1,261,197     146,728    $0.55\n  ollama/gemma3:12b                                   120    120      0     0      0      4h57m   1,037,866     138,258        —\n  ollama/qwen3:30b-a3b-instruct-2507-q4_K_M         1,643  1,627      0     0      0     23h39m  11,317,941   1,122,293        —\n  ollama/gemma3:4b                                    921    912      0     0      0      8h23m   2,355,608     672,157        —\n  ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n  TOTAL                                             3,331  3,279      0     0     10     47h22m  16,224,331   3,420,554  $104.12\n\n  By provider:\n  provider   calls   in-tokens  out-tokens      usd\n  ─────────────────────────────────────────────────\n  anthropic    452     251,719   1,341,118  $103.57\n  together     195   1,261,197     146,728    $0.55\n  ollama     2,684  14,711,415   1,932,708        —\n\n  By KB:\n  KB           calls  in-tokens  out-tokens      usd\n  ──────────────────────────────────────────────────\n  team-kb      1,732  7,020,329   2,211,137  $102.96\n  personal-kb  1,599  9,204,002   1,209,417    $1.16\n\n  Coverage: 3175/3331 calls had token data; the other 156 add ~$0.62 estimated, not shown above.\n  usd = provider-billed spend incl. cache-write & cache-read; in is uncached input, so usd exceeds an in/out list estimate.\n  cancl = sibling-canceled (rate-limit cascade).  tmout = ctx.DeadlineExceeded.\n```\n\nOn the local path there's no `claude -p`\n\ncallsite in a normal `scribe sync`\n\n: per-project extraction, two-pass absorb, the weekly Dream cycle, assess, deep, session-mine, and relations migrate all fire through bounded JSON-envelope subtasks against your Ollama server. A full weekly sync: **0 errors, $0.00, ~68s**, 7,447 → 7,472 articles. One line in `scribe.yaml`\n\nflips the whole pipeline.\n\nFor developers, the expensive half of the job isn't deciding. It's rebuilding the context you already had. scribe automates that half: if your Claude Code or Codex history is already full of decisions, fixes, and library evaluations, it keeps them from evaporating between sessions.\n\nYour agents keep re-deriving the same answers because each session starts from zero. scribe gives them durable memory.\n\n`CLAUDE.md`\n\n+ `AGENTS.md`\n\nOne cross-project KB means Friday's repo can pull Monday's fix. Typed edges keep the graph honest as patterns evolve.\n\n`supersedes`\n\n, `contradicts`\n\n, `specializes`\n\nRun the entire pipeline locally on Ollama. Plain markdown on your own git remote. No SaaS, no cloud sync, no vendor lock-in.\n\nTwo real loops from the maintainer's normal use: concrete, not marketing.\n\nscribe had already absorbed the verdict from the prior project's session: DB-backed Gettext with a LiveView admin UX, weighed against standard `.po`\n\nfiles and managed services. When Claude Code opened the new repo and asked the KB for translation options, the existing \"skip\" verdict surfaced first with the reasoning attached. No re-research; the agent cited the prior decision and moved on. The whole loop was invisible; the only thing the maintainer noticed was that the new project skipped the comparison shopping the first one did.\n\n`tools/kanta.md · verdict: skip`\n\n· surfaced via `qmd query \"phoenix translation library\"`\n\nThe fix from project A (an idempotency-key strategy for an external-call worker) got captured automatically when the post-fix session was mined into the KB. When the same race showed up in a different Phoenix app months later, the agent grepped the KB before guessing, found the prior pattern, and proposed the exact same shape with the prior trade-offs already weighed. The second fix took fifteen minutes instead of an afternoon.\n\n`solutions/oban-external-call-worker-idempotency.md`\n\n· linked from `solutions/fly-io-oban-cron-multi-node-double-fire.md`\n\n`sync --estimate`\n\ntoken preview`deep`\n\n/ `assess`\n\nbatch passes`_backlinks.json`\n\n· orphan linking · qmd BM25 + vector index`allowed_remotes`\n\n· promote-with-provenance · committed leader lease`scribe cost`\n\nreconciliation`scribe doctor`\n\nTwo commands to install. One `llm`\n\nblock in `scribe.yaml`\n\nroutes the whole pipeline local, hosted, or Anthropic. One query from any terminal.\n\n```\n# brew\nbrew tap oliver-kriska/scribe\nbrew install oliver-kriska/scribe/scribe\n\n# one-time setup\nscribe init --path ~/my-kb\ncd ~/my-kb\nscribe cron install\nscribe doctor\n\n# or via shell installer\ncurl -fsSL https://raw.githubusercontent.com/oliver-kriska/scribe/main/install.sh | bash\n# scribe.yaml — flip the whole pipeline onto local Ollama\nllm:\n  provider: ollama\n  model: gemma3:12b            # cross-op default\n  ollama_url: http://localhost:11434\n  num_ctx: 16384               # keeps dense-article tails intact\n\n# per-op overrides still work, e.g.\nops:\n  contextualize:\n    model: qwen3:30b-a3b       # quality-critical (MoE, fast)\n  pass2:\n    model: qwen3:30b-a3b       # highest-quality writes\n# scribe.yaml — run the same open models on a hosted GPU (~$2–6/mo)\nllm:\n  provider: together          # together | groq | fireworks | huggingface\n  model: MiniMaxAI/MiniMax-M3  # a real hosted model id, not a Claude alias\n  api_key_env: TOGETHER_API_KEY  # only the VAR NAME lives here — never the key\n  pricing:                      # optional, so `scribe cost` reports dollars\n    \"together/MiniMaxAI/MiniMax-M3\": { input: 0.30, output: 1.20 }\n\n# the key stays OUT of this file (a shared KB may commit it):\n#   ~/.config/scribe/config.yaml →  llm_api_key: tok-xxxx   (chmod 600)\n# heads-up: a hosted provider sees your KB content on every call.\n# scribe.yaml — the default: Anthropic via `claude -p` (your CLI auth)\nllm:\n  provider: anthropic         # the default; no API key in scribe, uses claude -p\n  model: sonnet               # cross-op default\n\n# per-op pinning: cheap entity pass on haiku, quality writes on sonnet\nabsorb:\n  pass1_model: haiku         # ≈ $0.0001/doc entity-list pass\n  pass2_model: sonnet        # highest-quality writes\n\n# runaway-spend backstop before any paid provider:\nsync:\n  daily_output_token_ceiling: 200000\n# from any terminal, any directory\nqmd query \"how did I solve the oban idempotency bug last quarter\"\n\n# exact-term search\nqmd search \"unique_constraint Multi\"\n\n# inside Claude Code — the MCP tool does the same query\nmcp__plugin_qmd_qmd__query\n# validate setup, cron, git remote, Ollama models\nscribe doctor\n\n# validate just the local-mode pipeline\nscribe doctor --section localmode\n\n# inspect what the last sync did\ncat output/runs/$(date +%Y-%m-%d).jsonl | tail -n 5\n```\n\nAfter `scribe init`\n\nand `scribe cron install`\n\n, the loop closes by itself. New work flows in, the KB grows, and the next Claude Code or Codex session, in any project, queries what scribe just wrote.\n\nA single walk over `~/.claude/projects/*`\n\nand `~/.codex/sessions/*`\n\nfinds every repo you've opened in either agent. Each one becomes an entry in the manifest with a stable name, last-seen timestamp, and source provenance. No config, no manual list; if you've coded there, scribe sees it.\n\n`discover()`\n\n+ cmd/scribe/codex.go: `discoverCodex()`\n\n→ `~/.claude/projects/*`\n\n+ `~/.codex/sessions/*`\n\n→ `manifest.Projects`\n\nscribe writes a maintained block into `~/.claude/CLAUDE.md`\n\nand `~/.codex/AGENTS.md`\n\n. Every Claude Code and Codex session, in every repo, picks up the same instructions: query the KB first, and drop reusable findings as files. The handshake is idempotent: re-run init and only that block updates.\n\n`installClaudeMD()`\n\n+ `installCodexMD()`\n\n→ `templates/claude-md-kb.md`\n\n+ `templates/codex-agents-md.md`\n\n→ marker-fenced block in both filesThree cron entries do the boring work: `sync`\n\nfor session mining and per-project extraction, `capture`\n\nfor queued URLs and self-sent iMessage links, and `sync --sessions`\n\non a faster cadence. Drop files written by an agent in any repo are picked up on the next tick and flow through density triage → contextualize → atomic facts → pass-2 absorb.\n\n`CronInstallCmd.Run()`\n\n→ launchd / systemd / crontab entries → `scribe sync`\n\n+ `scribe capture`\n\nA separate cron entry runs `scribe commit`\n\nevery hour: it stages everything the absorb pipeline produced, writes a structured commit message, and pushes to your private remote (GitHub, Gitea, Forgejo, anywhere). On non-fast-forward it runs `git pull --rebase`\n\nand retries once; force-push is never attempted. Your KB is version-controlled, diffable, and recoverable, with no web UI; the source of truth is markdown in git.\n\n`CommitCmd.Run()`\n\n+ cmd/scribe/gitops.go → `git add`\n\n· `git commit`\n\n· `git push origin main`\n\nOnce a week the Dream cycle wakes up. It looks at what's grown, prunes stubs that never got fleshed out, merges near-duplicates, breaks down articles that got too dense, and surfaces contradictions for review. Runs entirely on local Ollama: no token spend, no third party touches your notes. The KB stays small enough to fit in an agent's context window for years.\n\n`Sun 02:00`\n\n→ cmd/scribe/dream.go: `DreamCmd.Run()`\n\n→ `prompts/dream-ollama.md`\n\non gemma3:12bEvery absorb tick reindexes qmd, so the next Claude Code or Codex session, in any repo on this machine, finds what scribe just wrote. The loop closes itself, in the background, on a schedule you forget about.\n\nHere are the ones you'll actually type. Everything else is `scribe doctor`\n\n-discoverable.\n\n``` bash\n$ scribe init                        # bootstrap a KB, wire the agent handshake\n$ scribe sync                        # discover → extract → absorb → reindex\n$ scribe sync --sessions             # mine Claude Code + Codex transcripts\n$ scribe sync --estimate             # token estimate, zero LLM calls\n$ scribe doctor                      # validate setup, cron, git remote, Ollama\n$ scribe commit                      # stage + push the KB to your private remote\n$ scribe dream                       # weekly consolidation (Ollama-driven)\n$ scribe capture                     # drain queued URLs / iMessage links\n$ scribe relations migrate           # classify `related:` into typed edges\n$ scribe cron install / uninstall / status\n```\n\nThe same `qmd`\n\nindex is used by every consumer: your shell, Claude Code via MCP, Codex via MCP, your editor's grep, with no reindex per tool and no format conversion.\n\n```\n# ranked answers, anywhere on the machine\nqmd query \"oban idempotency pattern\"\n\n# exact keywords, no expansion\nqmd search \"BM25 density\"\n\n# open the top hit in $EDITOR\nqmd query \"two-pass absorb\" --open\n# the agent calls this directly\nmcp__plugin_qmd_qmd__query(\n  searches: [{ type: 'vec',\n              query: \"oban idempotency\" }],\n  intent: \"find the prior fix\"\n)\n\n# returns ranked hits + frontmatter;\n# the agent then reads the top file\n```\n\n`claude -p`\n\ncallsite in a normal `scribe sync`\n\n. A single line in `scribe.yaml`\n\nflips the whole pipeline. Per-op overrides still work if you want to keep some passes on Anthropic.`claude -p`\n\ncallsite in a normal `scribe sync`\n\n, including per-project extraction and the weekly Dream cycle, runs locally. On the Anthropic-hosted path, contextualize costs roughly `scribe.yaml`\n\nas untrusted by default: a pushed change that repoints inference or widens ingest paths reverts to the last trusted snapshot until a human approves it. A deterministic secret-scan gate holds API keys and tokens back before they reach shared git history (a regex pass on the commit path, no LLM, no network). `allowed_remotes`\n\ngates discovery by git-remote identity, so a teammate's unrelated or client repo never leaks in. `scribe promote`\n\nmoves curated pages into the team KB with provenance, and a committed leader lease elects the single machine that runs the weekly consolidation: no server, no etcd.`scribe cron install`\n\n; Linux gets paste-ready crontab lines from the same command. The fsnotify watcher (`scribe watch`\n\n) is not cron-friendly on either OS; run it under launchd KeepAlive on macOS or systemd-user on Linux. The iMessage capture step is macOS-only because it reads `chat.db`\n\n; everything else is portable.`scribe init`\n\n. Push it to your own GitHub, Gitea, or Forgejo; there's no SaaS account, no cloud sync, no vendor lock-in. Open it in Obsidian, VS Code, vim, or mdbook.`scribe init`\n\nand `scribe cron install`\n\n, and the knowledge base grows on its own.`scribe.yaml`\n\nflips every LLM op (extraction, absorb, dream, session-mine) to local. Your knowledge base is a plain git repo of markdown on your own machine, with no SaaS account and no cloud sync.`qmd`\n\nfor `grep`\n\nit from any terminal or query it from inside your agent. The whole pipeline runs unattended on macOS LaunchAgents or Linux cron.One `brew install`\n\n, one `scribe init`\n\n, and your tools start writing the notes for you.", "url": "https://wpnews.pro/news/show-hn-scribe-a-cli-that-builds-ai-agent-memory-from-your-repos-and-sessions", "canonical_source": "https://getscribe.dev/", "published_at": "2026-07-17 04:44:16+00:00", "updated_at": "2026-07-17 05:21:28.541337+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "artificial-intelligence", "ai-agents"], "entities": ["Scribe", "Claude Code", "Codex", "Ollama", "GitHub", "Gitea", "Forgejo", "Obsidian"], "alternates": {"html": "https://wpnews.pro/news/show-hn-scribe-a-cli-that-builds-ai-agent-memory-from-your-repos-and-sessions", "markdown": "https://wpnews.pro/news/show-hn-scribe-a-cli-that-builds-ai-agent-memory-from-your-repos-and-sessions.md", "text": "https://wpnews.pro/news/show-hn-scribe-a-cli-that-builds-ai-agent-memory-from-your-repos-and-sessions.txt", "jsonld": "https://wpnews.pro/news/show-hn-scribe-a-cli-that-builds-ai-agent-memory-from-your-repos-and-sessions.jsonld"}}