culi

module

v0.5.1 Latest Latest Go to latest Published: Jul 30, 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 ☕

Local context control for Claude Code and OpenAI Codex.

One trusted knowledge store. Only the relevant cards reach each prompt. Useful lessons come back for review.

culi (cà phê culi — the single dense peaberry bean) is the memory and context layer between your coding agents and your projects. It stores rules, lessons, styles, patterns, skills, and agent definitions as small Markdown cards, then routes a token-budgeted selection to Claude Code or Codex.

It is local-first, git-backed, and inspectable. Hooks and retrieval make no model calls; optional background learning proposes new knowledge for review. No Node, Python, or resident daemon is required.

What you get

One cross-agent memory for Claude Code and Codex, with explicit claude:<id> and codex:<id> provenance.
Small, relevant context through hooks, with deeper on-demand retrieval through MCP.
Background learning through Codex CLI, OpenAI API, Claude CLI, Anthropic API, or Ollama.
Codex history recovery from its read-only local rollout database, automatically throttled and deduplicated when hooks do not provide a transcript path.
A production-style local console for review, knowledge maintenance, delivery activity, Knowledge Pulse analytics, backend configuration, and light/dark themes.
Plain files as truth under ~/.culi/knowledge/; SQLite holds rebuildable card-search tables plus preserved local activity state.

Why culi?

Without culi	With culi
Guidance is copied across `CLAUDE.md`, `AGENTS.md`, agents, and skills	One canonical, git-versioned card store
Every session loads large instruction files	Only prompt-relevant cards are packed under a hard budget
Claude and Codex learn separately	Both agents contribute to and retrieve from the same knowledge
Useful corrections disappear in old transcripts	Lessons are mined, deduplicated, and placed in a review queue
Context delivery is invisible	Activity and Knowledge Pulse show what was delivered, where, and to which harness

Quick start

go install github.com/hung12ct/culi/cmd/culi@latest
culi init                       # auto-detect Claude Code and Codex
culi serve                      # http://localhost:7378

Open a new coding-agent session after initialization. Codex users should run /hooks once and trust the four generated Culi hooks. Verify the wiring with:

culi doctor --harness=codex

Ollama is optional. Without it, retrieval uses SQLite FTS/BM25. For semantic retrieval, install Ollama and run ollama pull nomic-embed-text.

For harness-specific setup, adding your first cards, and importing existing instructions, see the getting started guide.

Console

The local console makes Culi's behavior visible and reversible: review proposed lessons, search and edit cards, filter delivery activity by agent/repository/date, compare hot cards across Claude and Codex, and safely tune the learning backend.

Home — health, next actions, and savings	Review — evidence-first lesson decisions

See the console guide and full screenshot gallery.

How it works

prompt ──► cheap gate ──► scope + keyword + optional semantic retrieval
                                      │
                              rank + budgeted pack
                                      │
                         Claude Code or Codex
                                      │
session transcript ──► background mining ──► review ──► knowledge cards

Push: lifecycle hooks inject the best-fitting context. Any failure produces no injection and never blocks the coding agent.
Pull: the local MCP server exposes search_context, expand_card, and save_lesson.
Learn: detached workers mine transcripts, synthesize style, and extract durable lessons under daily call/spend caps.
Govern: imports and generated knowledge are staged or git-backed; retiring a card is reversible and hand-authored files are not silently rewritten.

Learning backends

Provider	Authentication	Billing path
`codex-cli`	Existing `codex login`	ChatGPT/Codex account quota
`openai`	`OPENAI_API_KEY` or key file	Metered OpenAI API
`claude-cli`	Existing Claude Code login or token file	Claude subscription quota
`anthropic`	`ANTHROPIC_API_KEY` or key file	Metered Anthropic API
`ollama`	Local endpoint	Local compute
`none`	None	Learning disabled; retrieval remains active

The default auto provider tries configured APIs first, then signed-in Claude and Codex terminals. Ollama is opt-in so Culi never silently chooses an unprepared local generation model. Model calls never occur in prompt hooks.

See learning and cost for Codex backfill, authentication, caps, model defaults, and manual learning commands.

Documentation

Getting started — install, initialize, verify, and add knowledge.
Console — Home, Review, Knowledge Pulse, Activity, Settings, and themes.
Knowledge and imports — card format, scopes, import/merge/apply, export, and git generation.
Learning and cost — providers, auth, Codex recovery, caps, and troubleshooting.
Configuration — complete config.yaml reference and safe console settings.
Product vision — principles and future direction.

Common commands

Command	Purpose
`culi init [--harness=auto\|claude\|codex\|all]`	Create the store and register selected hooks + MCP
`culi serve`	Start the local control console
`culi doctor --harness=codex`	Check Codex hooks, MCP, scanner health, and learning backlog
`culi query <text>`	Inspect retrieval from the terminal
`culi stats`	Show context savings, gate behavior, and learning spend
`culi learn`	Mine queued transcripts once
`culi learn --scan-codex --dry-run`	Preview discoverable Codex history without writing
`culi import scan\|merge\|apply`	Reconcile existing agent instructions into cards
`culi gen --repo X --target=claude\|codex\|both`	Generate repo instructions and cards from git history
`culi review`	Approve or reject proposed cards in the terminal

Run culi help for the complete command list.

Safety contracts

Hook failures fail open: empty output, exit 0, never block the agent.
Prompt-path retrieval has no LLM calls and enforces its token cap twice.
API spend and all-provider call counts have daily hard limits.
Culi's own terminal-model calls are marked internal to prevent self-learning loops.
Knowledge files are canonical; runtime SQLite state is migrated or rebuildable as appropriate.
Destructive knowledge changes remain explicit and reversible.

Requirements

Go 1.25+ for go install (the Go toolchain can download the pinned version automatically).
Claude Code with lifecycle hooks and MCP, and/or Codex CLI 0.145+.
Ollama with nomic-embed-text is optional.

Status

Actively developed and dogfooded daily. Built on gopheragent. Issues and ideas are 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 and Codex: 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 and Codex: 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.
harness Package harness names the coding agents culi integrates with (Claude Code, Codex CLI) and owns their identity: the typed enum, its validation, and the session-id encoding shared by the hook, learn, and serve layers.	Package harness names the coding agents culi integrates with (Claude Code, Codex CLI) and owns their identity: the typed enum, its validation, and the session-id encoding shared by the hook, learn, and serve layers.
hook Package hook implements normalized Claude Code and Codex hook handlers.	Package hook implements normalized Claude Code and Codex 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/codexroll Package codexroll normalizes Codex rollout JSONL into the conversation entries consumed by the learning miner.	Package codexroll normalizes Codex rollout JSONL into the conversation entries consumed by the learning miner.
learn/codexscan Package codexscan discovers Codex rollout transcripts from Codex's local state databases.	Package codexscan discovers Codex rollout transcripts from Codex's local state databases.
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.