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.
brew install oliver-kriska/scribe/scribe
scribe 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.
Git 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.
Keyword-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.
Auto-generated wikilinks, backlinks JSON, and retrieval-context paragraphs spliced into every article so embeddings catch implicit entities. qmd reindexes for semantic search, reachable from any terminal, in any directory, or from inside Claude Code via MCP.
scribe 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.
scribe init writes a handshake block into both ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md, so every session in every project queries your KB before recommending a library or proposing an architecture.
Hourly 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.
One 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.
Per-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 flips the whole pipeline. Zero API spend.
File 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.
Articles connect via a closed 10-kind typed-edge schema: supersedes, contradicts, derived_from, specializes, extends, and five more. scribe relations migrate classifies existing related: links into it with an LLM.
--- type: decision tags: [ecto, postgres, multi-tenancy] supersedes: [[ecto-transaction]] --- # Row-level tenancy over schema-per-tenant Chose a tenant_id column with Postgres RLS over a schema per tenant: migrations stay single-pass and the pool doesn't fan out per tenant. Why: schema-per-tenant broke oban job routing and made advisory locks table-ambiguous under load. ## See also - [[oban-idempotency]] · dedupe key includes tenant_id - [[genserver-backpressure]] · per-tenant rate isolation
[[wikilinks]]. Those links are the edges the graph below draws.The whole surface, in numbers — every figure is checkable against scribe --help and scribe.yaml, not marketing. Local mode needs no key at all; the default Anthropic path signs in through your claude -p CLI, not an API key.
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.
| Capability | scribe | RAGLangChain · LlamaIndex | Code Insights@code-insights/cli | AnythingLLM | Obsidian |
|---|---|---|---|---|---|
| Auto-written from your dev work | Yes | You index docs | Yes | You upload docs | You type notes |
| Sources captured | Sessions + git + URLs | Docs you feed | Coding sessions only | Docs you upload | Notes you write |
| Output is portable markdown in git | Yes | Vector chunks | SQLite dashboard | Vector store | Yes |
| Vector DB required? | Not needed | Required | Not needed | Required | Not needed |
| Full-text (BM25) search | qmd · FTS5 | Vector recall only | Dashboard analytics | Vector chat | Yes |
| Agents read it back before deciding | CLAUDE.md / AGENTS.md | If you wire it | Human dashboard | You chat with it | No |
| Local-first, no API key (Ollama) | 100% Ollama | Local embeddings | Ollama option | Local LLM + DB | AI add-ons need keys |
scribe is the only one of these that auto-writes a portable, git-versioned markdown wiki your agents read before they decide, with no vector database. Unlike AnythingLLM, scribe stores plain markdown in git and needs no vector database or running server. Snapshot 2026-06-08; tool capabilities change, so check each project's docs before deciding.
| Tool | Session mining | Cron-driven | Density pre-filter | Two-pass absorb | Multi-project | Local-mode |
|---|---|---|---|---|---|---|
| scribecurated wiki + raw sources, in git | Claude + Codex | launchd / systemd | BM25 | atomic facts → pass-2 | manifest-tracked | 100% Ollama |
| claude-memory-compilerAnthropic-only, single project | Claude only · $115 / 20min · issue #3 | manual | none | single-pass | single repo | API only |
| nvk/llm-wikiLLM-built wiki, no mining | user-fed | manual | none | single-pass | single repo | Ollama possible |
| basic-memoryMCP memory server | issue #669 since Mar | request-driven | none | single-pass | per-MCP-client | local embeddings |
| RAG (LangChain, LlamaIndex)retrieve-then-prompt | retrieves chunks | on-query | vector recall | no absorb | per-index | local embeddings |
| Obsidian / Notionmanual notes tool | you type it | manual | tag-based | no absorb | vault / workspace | Obsidian = local, Notion = cloud |
Snapshot 2026-06-08. Everything moves; check the source repos before deciding. Verdicts are pulled from public READMEs, issue trackers, and the scribe maintainer's tool evaluations.
scribe 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
scribe 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.
A trust layer pins the sensitive surface of a shared scribe.yaml: 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.
scribe 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.
Every scribe sync pulls, 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.
Discovered projects start pending. allowed_remotes and source filters gate discovery by git-remote identity, and scribe projects {list,approve,ignore,review} controls what enters the pipeline, so a side project or a client checkout never lands in the shared KB without an approve.
scribe promote <article> --to team-kb copies 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.
The 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.
Run 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 for the Anthropic path. The three coexist; pick the trade per op in scribe.yaml, and nothing reaches a paid provider without explicit config. scribe cost then reconciles every token across providers and KBs, to the cent against the provider's own dashboard.
~ $ scribe cost
scribe cost — last 7 days — 2 KBs (personal-kb, team-kb)
model calls ok cancl rate tmout wallclock in-tokens out-tokens usd
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
sonnet 301 281 0 0 3 6h54m 250,468 789,357 $92.80
haiku 151 144 0 0 7 2h21m 1,251 551,761 $10.77
together/Qwen/Qwen3-235B-A22B-Instruct-2507-tput 195 195 0 0 0 1h06m 1,261,197 146,728 $0.34
ollama/gemma3:12b 120 120 0 0 0 4h57m 1,037,866 138,258 —
ollama/qwen3:30b-a3b-instruct-2507-q4_K_M 1,643 1,627 0 0 0 23h39m 11,317,941 1,122,293 —
ollama/gemma3:4b 921 912 0 0 0 8h23m 2,355,608 672,157 —
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
TOTAL 3,331 3,279 0 0 10 47h22m 16,224,331 3,420,554 $103.91
By provider:
provider calls in-tokens out-tokens usd
─────────────────────────────────────────────────
anthropic 452 251,719 1,341,118 $103.57
together 195 1,261,197 146,728 $0.34
ollama 2,684 14,711,415 1,932,708 —
By KB:
KB calls in-tokens out-tokens usd
──────────────────────────────────────────────────
team-kb 1,732 7,020,329 2,211,137 $102.96
personal-kb 1,599 9,204,002 1,209,417 $0.95
Coverage: 3175/3331 calls had token data; the other 156 add ~$0.62 estimated, not shown above.
usd = provider-billed spend incl. cache-write & cache-read; in is uncached input, so usd exceeds an in/out list estimate.
cancl = sibling-canceled (rate-limit cascade). tmout = ctx.DeadlineExceeded.
Real output, names anonymized. Same machine, same week, three provider paths: Anthropic billed $103.57, the hosted Together path $0.34, the local Ollama models nothing. The paths handled different volumes (routing is per-op in scribe.yaml), so read each as what it actually billed, not a like-for-like race. One API key usually bills every KB on a machine, so scribe cost aggregates them by default and reconciles to the dashboard.
On the local path there's no claude -p callsite in a normal scribe sync: 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 flips the whole pipeline.
For 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.
Your agents keep re-deriving the same answers because each session starts from zero. scribe gives them durable memory.
CLAUDE.md + AGENTS.mdOne cross-project KB means Friday's repo can pull Monday's fix. Typed edges keep the graph honest as patterns evolve.
supersedes, contradicts, specializesRun the entire pipeline locally on Ollama. Plain markdown on your own git remote. No SaaS, no cloud sync, no vendor lock-in.
Two real loops from the maintainer's normal use: concrete, not marketing.
scribe had already absorbed the verdict from the prior project's session: DB-backed Gettext with a LiveView admin UX, weighed against standard .po files 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.
tools/kanta.md · verdict: skip · surfaced via qmd query "phoenix translation library"The 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.
solutions/oban-external-call-worker-idempotency.md · linked from solutions/fly-io-oban-cron-multi-node-double-fire.mdsync --estimate token previewdeep / assess batch passes_backlinks.json · orphan linking · qmd BM25 + vector indexallowed_remotes · promote-with-provenance · committed leader leasescribe cost reconciliationscribe doctorTwo commands to install. One llm block in scribe.yaml routes the whole pipeline local, hosted, or Anthropic. One query from any terminal.
# brew brew tap oliver-kriska/scribe brew install oliver-kriska/scribe/scribe # one-time setup scribe init --path ~/my-kb cd ~/my-kb scribe cron install scribe doctor # or via shell installer curl -fsSL https://raw.githubusercontent.com/oliver-kriska/scribe/main/install.sh | bash
# scribe.yaml — flip the whole pipeline onto local Ollama llm: provider: ollama model: gemma3:12b # cross-op default ollama_url: http://localhost:11434 num_ctx: 16384 # keeps dense-article tails intact # per-op overrides still work, e.g. ops: contextualize: model: qwen3:30b-a3b # quality-critical (MoE, fast) pass2: model: qwen3:30b-a3b # highest-quality writes
# scribe.yaml — run the same open models on a hosted GPU (~$2–6/mo) llm: provider: together # together | groq | fireworks | huggingface model: qwen3-30b-a3b # a real hosted model id, not a Claude alias api_key_env: TOGETHER_API_KEY # only the VAR NAME lives here — never the key pricing: # optional, so `scribe cost` reports dollars "together/qwen3-30b-a3b": { input: 0.10, output: 0.30 } # the key stays OUT of this file (a shared KB may commit it): # ~/.config/scribe/config.yaml → llm_api_key: tok-xxxx (chmod 600) # heads-up: a hosted provider sees your KB content on every call.
# scribe.yaml — the default: Anthropic via `claude -p` (your CLI auth) llm: provider: anthropic # the default; no API key in scribe, uses claude -p model: sonnet # cross-op default # per-op pinning: cheap entity pass on haiku, quality writes on sonnet absorb: pass1_model: haiku # ≈ $0.0001/doc entity-list pass pass2_model: sonnet # highest-quality writes # runaway-spend backstop before any paid provider: sync: daily_output_token_ceiling: 200000
# from any terminal, any directory qmd query "how did I solve the oban idempotency bug last quarter" # exact-term search qmd search "unique_constraint Multi" # inside Claude Code — the MCP tool does the same query mcp__plugin_qmd_qmd__query
# validate setup, cron, git remote, Ollama models scribe doctor # validate just the local-mode pipeline scribe doctor --section localmode # inspect what the last sync did cat output/runs/$(date +%Y-%m-%d).jsonl | tail -n 5
After scribe init and scribe cron install, 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.
A single walk over ~/.claude/projects/* and ~/.codex/sessions/* finds 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.
discover() + cmd/scribe/codex.go: discoverCodex() → ~/.claude/projects/* + ~/.codex/sessions/* → manifest.Projectsscribe writes a maintained block into ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md. 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.
installClaudeMD() + installCodexMD() → templates/claude-md-kb.md + templates/codex-agents-md.md → marker-fenced block in both filesThree cron entries do the boring work: sync for session mining and per-project extraction, capture for queued URLs and self-sent iMessage links, and sync --sessions on 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.
CronInstallCmd.Run() → launchd / systemd / crontab entries → scribe sync + scribe captureA separate cron entry runs scribe commit every 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 and 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.
CommitCmd.Run() + cmd/scribe/gitops.go → git add · git commit · git push origin mainOnce 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.
Sun 02:00 → cmd/scribe/dream.go: DreamCmd.Run() → prompts/dream-ollama.md on 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.
Here are the ones you'll actually type. Everything else is scribe doctor-discoverable.
$ scribe init # bootstrap a KB, wire the agent handshake
$ scribe sync # discover → extract → absorb → reindex
$ scribe sync --sessions # mine Claude Code + Codex transcripts
$ scribe sync --estimate # token estimate, zero LLM calls
$ scribe doctor # validate setup, cron, git remote, Ollama
$ scribe commit # stage + push the KB to your private remote
$ scribe dream # weekly consolidation (Ollama-driven)
$ scribe capture # drain queued URLs / iMessage links
$ scribe relations migrate # classify `related:` into typed edges
$ scribe cron install / uninstall / status
Run scribe --help to see all 45. scribe cron install puts the boring ones on a schedule so you never type them again.
The same qmd index 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.
# ranked answers, anywhere on the machine qmd query "oban idempotency pattern" # exact keywords, no expansion qmd search "BM25 density" # open the top hit in $EDITOR qmd query "two-pass absorb" --open
# the agent calls this directly mcp__plugin_qmd_qmd__query( searches: [{ type: 'vec', query: "oban idempotency" }], intent: "find the prior fix" ) # returns ranked hits + frontmatter; # the agent then reads the top file
claude -p callsite in a normal scribe sync. A single line in scribe.yaml flips the whole pipeline. Per-op overrides still work if you want to keep some passes on Anthropic.claude -p callsite in a normal scribe sync, including per-project extraction and the weekly Dream cycle, runs locally. On the Anthropic-hosted path, contextualize costs roughly $0.0001 per article via Claude Haiku; project extraction, pass-2, and dream use Sonnet at standard prices. The triage pre-filter and density scoring never call an LLM, so most session-mining work is free regardless of backend.scribe.yaml as 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 gates discovery by git-remote identity, so a teammate's unrelated or client repo never leaks in. scribe promote moves 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; Linux gets paste-ready crontab lines from the same command. The fsnotify watcher (scribe watch) 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; everything else is portable.scribe init. 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 and scribe cron install, and the knowledge base grows on its own.scribe.yaml flips 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 for BM25 keyword search and semantic vector search, and because it's plain markdown you can also grep it from any terminal or query it from inside your agent. The whole pipeline runs unattended on macOS LaunchAgents or Linux cron.One brew install, one scribe init, and your tools start writing the notes for you.