scribe reads your git history, coding-agent 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
The pain of re-deriving context you already had, what scribe does about it, and how it becomes memory your agents read before they act.
The expensive half of the job was never deciding. It's rebuilding the context you already had. Close the terminal, and the fix you just earned is gone. Every new agent session starts from zero, re-deriving what you already know. scribe reads your git history, your Claude Code and Codex sessions, and the links you send yourself, and writes the wiki for you. Memory your agents read before they act. Not a second brain you maintain and never reopen. It runs on cron. Four streams in, noise filtered before any model runs, compiled into a typed graph of plain markdown. Fix a nasty bug in one project on Monday. Friday, in a different repo, your agent already has your fix. Not RAG. Not Obsidian. Not another model-on-every-session burner. Plain markdown in git you own, running fully local for zero dollars. scribe. Set it up once, and your tools write the notes for you. Install at getscribe.dev.
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, coding-agent sessions via ccrider, URLs you text yourself, and drop files from other projects. scribe also auto-discovers every codebase you've opened in Claude Code or Codex and keeps the manifest fresh.
Keyword-density scoring rejects boilerplate session candidates before any LLM call, so cheap sessions cost nothing. Sessions and project changes use bounded extraction envelopes; raw articles and drop files use a two-pass absorb that grounds facts, then fans dense sources into 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 maintained handshake blocks into ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, and ~/.config/amp/AGENTS.md, so Claude Code, Codex, and Amp query 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 | all ccrider providers + direct Codex | launchd / systemd | FTS5 | 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.
Now imagine that memory isn't just yours. A new teammate asks the question you answered six months ago. The decision is in your head, or in a session nobody can find. scribe scales to your team. Every engineer's agent sessions write to one shared, git-backed knowledge base. Every fix, every rejected library, every decision your team makes becomes context the whole team's agents read before they act. A new hire's first Claude Code session already knows why you chose what you chose. Shared memory is a trust problem, not a sync problem. A secret gate scans every commit, so no key ever leaks into the wiki. Allowed remotes lock which repos it reads. Every promoted note carries where it came from. Still plain markdown in a repo your team owns. scribe. One knowledge base, the whole team writes to it. Single-user by default, team-ready when you are. Install at getscribe.dev.
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/MiniMaxAI/MiniMax-M3 195 195 0 0 0 1h06m 1,261,197 146,728 $0.55
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 $104.12
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.55
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 $1.16
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.55, 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 coding-agent 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 --dry-run --estimate token previewdeep / assess batch passes_backlinks.json · orphan linking · qmd BM25 + vector indexallowed_remotes · promote-with-provenance · committed leader leasescribe cost reconciliationscribe doctorOne guided init, then explicit source approval and verification. The setup runbook has copyable personal, Ollama, hosted-provider, team-owner, and team-member recipes. One llm block in scribe.yaml routes the whole pipeline local, hosted, or Anthropic.
# brew brew tap oliver-kriska/scribe brew install oliver-kriska/scribe/scribe # one-time setup scribe init --path ~/my-kb --bind cd ~/my-kb scribe skill install scribe sync --discover scribe projects review scribe sync --dry-run --estimate scribe cron install scribe doctor # or via shell installer curl -fsSL https://raw.githubusercontent.com/oliver-kriska/scribe/main/install.sh | bash
Read https://getscribe.dev/setup.md and set up scribe on this machine. Before changing anything, ask me for the setup profile, KB path, and LLM provider. For a team setup, also ask whether I am creating or joining the KB and ask for the private git remote. Inspect existing state before changing it. Execute the applicable steps; do not only explain them. Never use --force. Never print or commit secrets. Ask before the first real scribe sync because it may call an LLM and incur cost. Finish with the runbook's verification checklist and report what passed and what still needs human action.
# 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: MiniMaxAI/MiniMax-M3 # 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/MiniMaxAI/MiniMax-M3": { input: 0.30, output: 1.20 } # 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, Codex, or Amp session 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 maintained blocks into ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, and ~/.config/amp/AGENTS.md. Claude Code, Codex, and Amp pick up the same loop: query the KB first, then drop reusable findings as files. The handshake is idempotent: re-run init and only the marker-fenced blocks update.
installClaudeMD() + installCodexMD() + installAmpMD() → three agent-specific templates → marker-fenced blocks in each global instructions fileThree 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, Codex, or Amp session 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 --bind # bootstrap a KB, wire the agent handshake
$ scribe sync # discover → extract → absorb → reindex
$ scribe sync --sessions # mine coding-agent transcripts
$ scribe sync --dry-run --estimate # token estimate, no writes or 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 78. 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 "FTS5 triage" # 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. macOS release binaries are Developer ID signed and notarized, and scribe fda verifies chat.db access in the same launchd context scheduled capture uses.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.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.Use the personal, local Ollama, hosted-provider, or team recipe. The same runbook can be pasted into Claude Code or Codex so it performs the setup and proves what works.