culi

module

v0.1.0 Latest Latest Go to latest Published: Jul 21, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/hung12ct/culi

Links

Open Source Insights

README ¶

culi ☕

Context orchestrator for Claude Code — one canonical knowledge store, injected only when it's relevant, so every prompt gets the right rules without paying to dump your whole CLAUDE.md every time.

culi (cà phê culi — the single dense peaberry bean) keeps all your Claude Code context — rules, skills, lessons, styles, patterns — as small markdown "cards" in one place. On every prompt it pushes just the most relevant, token-budgeted slice into Claude via hooks, lets Claude pull more on demand via an MCP server, and quietly learns new lessons from your sessions.

In short: self-improving agent memory and context engineering for Claude Code — the memory-and-context layer that plugs into its harness and decides what Claude should know at each step, so you stop re-teaching it and stop paying for context it doesn't need.

No Node, no Python, no daemon required. One static Go binary.

Why culi?

If you use Claude Code across more than one repo, you probably have this problem:

Without culi	With culi
The same `CLAUDE.md`, agents & skills hand-copied into every repo	One canonical store, git-versioned
Copies drift — each repo slowly diverges	Drift is impossible — repos generate from cards
Every session dumps the entire `CLAUDE.md`, relevant or not	Only the cards that match this prompt are injected, under a hard token budget
You re-teach Claude the same lesson every week	culi mines your transcripts and remembers it

culi stats shows the payoff directly — tokens injected vs. "dump everything every session."

Screenshots

Overview	Review queue

Knowledge base	Activity — what culi injected, per conversation

Install

go install github.com/hung12ct/culi/cmd/culi@latest
culi init      # creates ~/.culi, registers the hook + MCP server in Claude Code

That's it. Open Claude Code in any repo and culi starts injecting context. Nothing else to run.

Optional: install Ollama and ollama pull nomic-embed-text for semantic retrieval. culi works without it (keyword/BM25) and degrades gracefully if it's ever down.

How it works

your prompt ─► [gate: skip acks/pastes] ─► scope + keyword + semantic match
                                                     │
                                          rank · token-budget pack
                                                     │
                                     ◄── inject only what fits ──►  Claude

Push — a Claude Code hook runs on each prompt, retrieves the best-matching cards, and injects a budgeted block. Fails open: any error → inject nothing, never blocks you.
Pull — an MCP server gives Claude three tools: search_context, expand_card, and save_lesson (tell Claude "remember this" and it writes a card — and folds it into an existing one instead of duplicating).
Learn — after a session ends, culi mines the transcript in the background for lessons and missing rules, dedupes them against what it already knows, and queues them for your review.
Files are truth — everything lives as plain markdown in ~/.culi/knowledge/ (git-init'd). The search index is disposable and rebuilds from the files.

The review console

culi serve      # → http://localhost:7378

A local web UI to see and steer everything culi does: a health overview with real token-savings, a review queue for mined candidate cards, a searchable knowledge base, and an activity log showing exactly which cards Claude saw in each conversation (and why).

Commands

Command	What it does
`culi init`	Set up `~/.culi`, register hooks + MCP in Claude Code
`culi serve`	Local web review console (default `localhost:7378`)
`culi query <text>`	Debug retrieval from the terminal
`culi stats`	Token accounting, gate economics, learning spend
`culi import scan\|merge\|apply`	Reconcile drifted `.claude` dirs into the store
`culi export`	Regenerate `~/.claude` agents/skills from cards
`culi learn`	Mine queued session transcripts into candidate cards
`culi review`	Approve/reject mined candidates
`culi gen --repo X`	Turn git history into `CLAUDE.md` + repo cards
`culi card list\|show\|rm`	Inspect the card store

What makes it different

Token budget is a hard cap, enforced twice — culi never blows past your limit.
Nothing heavy on the prompt path — no LLM calls, stdlib-only hot path, sub-100ms p95.
Learning has spend caps — daily USD and call limits, so it never eats your API budget or subscription quota.
One static binary (CGO_ENABLED=0) — no runtime zoo to break on the next OS update.
Your content is never destroyed — retiring a card is a reversible status flip; hand-authored files are never rewritten.

Requirements

Go 1.25+ to install (the toolchain auto-downloads if needed)
Claude Code (hooks + MCP)
Ollama with nomic-embed-text — optional, for semantic search

Status

Actively developed and dogfooded daily. Built on gopheragent. Issues and ideas welcome.

License

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
culi command Command culi is the context orchestrator for Claude Code: a canonical knowledge-card store, token-budgeted context injection via hooks, and (in later phases) MCP retrieval and background learning.	Command culi is the context orchestrator for Claude Code: a canonical knowledge-card store, token-budgeted context injection via hooks, and (in later phases) MCP retrieval and background learning.
internal
cli Package cli implements the non-hook subcommands.	Package cli implements the non-hook subcommands.
config Package config loads ~/.culi/config.yaml with defaults.	Package config loads ~/.culi/config.yaml with defaults.
embed Package embed provides the local-embedding arm of the hybrid funnel: an Ollama-backed Embedder plus the f32 vector codec and similarity helper.	Package embed provides the local-embedding arm of the hybrid funnel: an Ollama-backed Embedder plus the f32 vector codec and similarity helper.
export Package export regenerates ~/.claude/agents and ~/.claude/skills from canonical cards, so Claude Code merges them into every repo natively and per-repo copies can be deleted.	Package export regenerates ~/.claude/agents and ~/.claude/skills from canonical cards, so Claude Code merges them into every repo natively and per-repo copies can be deleted.
hook Package hook implements the Claude Code hook handlers.	Package hook implements the Claude Code hook handlers.
importer Package importer reconciles drifted .claude directories and CLAUDE.md files from the user's repos into the canonical knowledge store.	Package importer reconciles drifted .claude directories and CLAUDE.md files from the user's repos into the canonical knowledge store.
indexer Package indexer syncs the knowledge file store into the SQLite index.	Package indexer syncs the knowledge file store into the SQLite index.
knowledge Package knowledge defines the card model and parses the canonical file store.	Package knowledge defines the card model and parses the canonical file store.
learn Package learn is the background learning worker: it drains the SessionEnd inbox through the mining pipeline under a lockfile, per-transcript cursors, and the llmtier spend caps.	Package learn is the background learning worker: it drains the SessionEnd inbox through the mining pipeline under a lockfile, per-transcript cursors, and the llmtier spend caps.
learn/branchgen Package branchgen implements learning pipeline C (`culi gen`): repository git facts → two one-shot structured calls (Strong drafts CLAUDE.md sections, Cheap extracts repo-scoped cards) → idempotent writes.	Package branchgen implements learning pipeline C (`culi gen`): repository git facts → two one-shot structured calls (Strong drafts CLAUDE.md sections, Cheap extracts repo-scoped cards) → idempotent writes.
learn/gitfacts Package gitfacts renders a deterministic, zero-LLM analysis of a git repository: modules and churn, commit conventions, dependencies, build/test layout, branch-unique work, and the existing CLAUDE.md as a prior.	Package gitfacts renders a deterministic, zero-LLM analysis of a git repository: modules and churn, commit conventions, dependencies, build/test layout, branch-unique work, and the existing CLAUDE.md as a prior.
learn/llmtier Package llmtier gives the learning pipelines their model access: an explicit Cheap/Strong generator pair (plan §cost control) behind the multi-backend llmgen seam, gated by a persistent daily spend ledger.	Package llmtier gives the learning pipelines their model access: an explicit Cheap/Strong generator pair (plan §cost control) behind the multi-backend llmgen seam, gated by a persistent daily spend ledger.
learn/mine Package mine implements learning pipeline A: deterministic signal windows from one session's transcript → a single cheap structured call (escalated once on failure) → deduplicated candidate cards with a reinforcement lifecycle.	Package mine implements learning pipeline A: deterministic signal windows from one session's transcript → a single cheap structured call (escalated once on failure) → deduplicated candidate cards with a reinforcement lifecycle.
learn/patterns Package patterns implements learning pipeline D: an offline cross-branch pattern index.	Package patterns implements learning pipeline D: an offline cross-branch pattern index.
learn/queue Package queue manages the learn inbox: job files written by the SessionEnd hook, a lockfile so only one worker mines at a time, and per-transcript byte cursors.	Package queue manages the learn inbox: job files written by the SessionEnd hook, a lockfile so only one worker mines at a time, and per-transcript byte cursors.
learn/style Package style implements learning pipeline B: periodic synthesis of the per-session style observations that the miner appends to state/style_observations.jsonl.	Package style implements learning pipeline B: periodic synthesis of the per-session style observations that the miner appends to state/style_observations.jsonl.
learn/transcript Package transcript reads Claude Code session transcripts (JSONL) and extracts deterministic signal windows for the learning miner — the zero-LLM stage 0 that decides whether a session is worth any model call at all.	Package transcript reads Claude Code session transcripts (JSONL) and extracts deterministic signal windows for the learning miner — the zero-LLM stage 0 that decides whether a session is worth any model call at all.
llmgen Package llmgen is the multi-backend seam for one-shot structured LLM calls: system + user prompt in, schema-validated JSON out.	Package llmgen is the multi-backend seam for one-shot structured LLM calls: system + user prompt in, schema-validated JSON out.
mcpserver Package mcpserver exposes the card store to Claude Code as an MCP stdio server — the pull side of culi.	Package mcpserver exposes the card store to Claude Code as an MCP stdio server — the pull side of culi.
pack Package pack turns ranked candidates into a budgeted injection envelope.	Package pack turns ranked candidates into a budgeted injection envelope.
retrieve Package retrieve implements the token-minimal retrieval funnel: gate → scope filter + shadowing → trigger pinning → (BM25 ‖ embed+cosine) → RRF fuse × utility → floor.	Package retrieve implements the token-minimal retrieval funnel: gate → scope filter + shadowing → trigger pinning → (BM25 ‖ embed+cosine) → RRF fuse × utility → floor.
serve Package serve hosts the culi review console: a local, single-user web UI over the knowledge store (candidate triage, KB browse, token-savings and job-health dashboards).	Package serve hosts the culi review console: a local, single-user web UI over the knowledge store (candidate triage, KB browse, token-savings and job-health dashboards).
store Package store owns the SQLite index.	Package store owns the SQLite index.