Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@contextberg/agent-history) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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.

One UI, every agent	Claude Code, Cursor, Codex, OpenClaw, Hermes in a single searchable view. Source filter, tool-call expansion, conversation timeline.
Cross-agent dreaming	A managed `post-commit` hook scans every agent's history, picks the turns relevant to the changed files, and writes a per-commit knowledge note. Durable, version-controlled, agent-readable.
MCP-native replay	Raw history is exposed as the `get_agent_history` MCP tool. Any MCP-aware agent inherits the context — no copy-paste, no prompt scaffolding.
Bring your own LLM	Six providers out of the box: OpenAI, Anthropic, Google (Gemini), OpenRouter, Codex (ChatGPT subscription via OAuth), OpenCode Go. Switch with one command.
Local-first	Logs, summaries, and API keys live under `~/.agent-history/` (owner-only mode). Nothing leaves your machine unless you point it at a hosted LLM.
~50 LOC to add an agent	Implement one `IReader`, register it in three places, ship a PR. GitHub Copilot reader is the obvious next contribution.

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

Browse only (no install)

npx @contextberg/agent-history

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

Full setup — viewer + dreaming

npm install -g @contextberg/agent-history
contextberg setup

The wizard handles provider choice, OAuth or API key, model selection, token caps, and post-commit hook installation.

After that, git commit Just Works. To preview what the hook will do without committing:

contextberg learn --commit HEAD --verbose
contextberg show-prompt          # exact prompt the LLM will receive

Supported tools

Tool	Source on disk
Claude Code	`~/.claude/projects/*/.jsonl`
Cursor	`~/.cursor/projects/`
Codex	`~/.codex/sessions/`
OpenClaw	`~/.openclaw/agents/`
Hermes	`~/.hermes/state.db`
GitHub Copilot	🚧 Contributions welcome

CLI

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

Command	What it does
`agent-history`	Launch the browser UI on a free port and open it
`agent-history --mcp`	Run as an MCP stdio server
`contextberg setup`	Interactive wizard: provider, model, hook install
`contextberg learn`	Extract knowledge from `HEAD` (or `--commit <ref>`)
`contextberg status`	Show current config + per-repo hook status
`contextberg test`	One-shot prompt to verify provider auth
`contextberg show-prompt`	Print the full system prompt
`contextberg uninstall`	Remove the `post-commit` hook from this repo

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

git commit fires the managed post-commit hook
The diff and message are inspected; trivial / vendored changes are filtered out
Across all installed agent histories, the turns that touched the changed files are selected
Those turns + the diff are sent to your chosen LLM with a structured prompt (see contextberg show-prompt)
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[]>;
}

src/readers/<toolname>.ts — implement IReader
src/readers/types.ts — extend the AgentSource union
src/readers/index.ts — register in AgentHistoryService
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.