@contextberg/agent-history 💤

Your agents dream while you commit.

Claude Code keeps its history. Cursor keeps its own. Codex too. None of them read each other's.

agent-history reads all five — Claude Code, Cursor, Codex, OpenClaw, Hermes — into one searchable view. And on every git commit, it picks the cross-agent reasoning behind that change, distills it into a per-commit note in your repo, and serves it back over MCP.

We call this dreaming: autonomous, cross-session, cross-agent consolidation while you keep coding. The bridge between vibe coding and context engineering — handled for you.

The OSS module of Contextberg, a desktop assistant for coding agents. Use it standalone, or as part of the larger app.

Why

Two postures dominate AI coding today.

Vibe coding is fast. But every session starts from zero.

Context engineering is powerful. But no one keeps up the manual curation.

agent-history closes the gap with autonomous consolidation. You keep coding. Every commit triggers a cross-agent dream cycle. The wall between "vibe" and "engineered" disappears.

Quick Start

There are two ways to use agent-history. Dreaming requires the full install — npx alone gives you the viewer only.

1. Browse only — npx, no install

npx @contextberg/agent-history

The browser opens automatically. Five readers run in parallel. Tools you don't have installed silently no-op. No commit hook, no dreaming.

2. Full setup — viewer + dreaming on every commit

Dreaming is wired through a post-commit git hook that calls a globally installed binary, so this flow needs a real npm install -g (not npx) plus a one-time wizard:

# Step 1 — install the binaries globally so git hooks can find them
npm install -g @contextberg/agent-history

# Step 2 — run the wizard inside the repo you want dreaming on
cd path/to/your/repo
contextberg setup

The wizard walks you through:

1. Provider — OpenAI, Anthropic, Google (Gemini), OpenRouter, Codex via ChatGPT OAuth, or OpenCode Go
2. Auth — paste an API key, or run the device-code flow for Codex / OpenCode Go
3. Model + token caps — defaults are fine; override if you want
4. post-commit hook — installed into .git/hooks/post-commit of the current repo

That's it. The hook runs after the commit object is written — the commit itself never fails because of dreaming. The terminal does wait briefly for the LLM call to return; stderr is silenced and any error is swallowed (|| true), so a hiccup with your provider never breaks your git commit workflow. The summary lands at .contextberg/knowledge/YYYY-MM/DD/{slug}.md and is mirrored to ~/.agent-history/knowledge/<repo>/ for cross-repo MCP retrieval.

Verify it's working

contextberg status                       # config + per-repo hook status
contextberg test                         # one-shot prompt to confirm provider auth
contextberg learn --commit HEAD --verbose   # rerun against HEAD without committing
contextberg show-prompt                  # exact prompt the LLM will receive

Adding dreaming to additional repos

npm install -g is one-time. For each new repo, just run contextberg setup inside it (or contextberg uninstall to remove the hook).

Supported tools

CLI

Two binaries ship with the package — viewer/MCP on one, dreaming on the other.

Using as an MCP server

{
  "mcpServers": {
    "agent-history": {
      "command": "npx",
      "args": ["-y", "@contextberg/agent-history", "--mcp"]
    }
  }
}

Hard caps protect downstream context windows: maxSessions ≤ 50, maxTurnsPerSession ≤ 20, maxCharsPerField ≤ 2000.

How contextberg learn works

1. git commit fires the managed post-commit hook
2. The diff and message are inspected; trivial / vendored changes are filtered out
3. Across all installed agent histories, the turns that touched the changed files are selected
4. Those turns + the diff are sent to your chosen LLM with a structured prompt (see contextberg show-prompt)
5. The summary is written to .contextberg/knowledge/YYYY-MM/DD/{slug}.md in the repo, indexed via CHANGELOG.md, and mirrored to ~/.agent-history/knowledge/<repo>/ for cross-repo MCP retrieval

Filter logic, transcript packing, and prompt are all open and inspectable under src/knowledge/.

Roadmap

• GitHub Copilot reader
• Full-text search across sessions
• Cross-repo knowledge linking (problem solved in repo A → surfaced in repo B)
• Tag / favorite sessions
• Markdown export for a selected turn-set

Contributing

The most welcome contribution is a new reader. Implement the IReader interface and register it in three places.

export interface IReader {
  readonly source: AgentSource;
  isInstalled(): Promise<boolean>;
  read(options?: ReaderOptions): Promise<AgentSession[]>;
}

1. src/readers/<toolname>.ts — implement IReader
2. src/readers/types.ts — extend the AgentSource union
3. src/readers/index.ts — register in AgentHistoryService
4. src/mcp/server.ts — add to the schema enum

Local development:

git clone https://github.com/contextberg/agent-history
cd agent-history
npm install
# two terminals:
npm run dev:server
npm run dev:web

See .claude/CLAUDE.md for architectural conventions.

License

MIT — see LICENSE. Built by Contextberg.