agentrunlog
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
AgentRunlog π§ β‘
Typed Engineering Memory & Karpathy LLM Wiki for Autonomous Coding Agents.
Never let your coding agents make the same mistake twice.
π Problem & Vision
Across coding sessions, context is lost:
π Re-invented wheels & reversed decisions: The agent forgets why an architectural choice was made and reverts it.
π³οΈ Dead-end traps: The agent repeatedly attempts failed solutions, debugging methods, or broken libraries.
π Wasted time & tokens: Every session starts with an amnesic agent requiring manual context re-feeding.
AgentRunlog solves this by implementing Andrej Karpathy's LLM Wiki Pattern tailored specifically for coding agents. It captures raw transcripts, automatically sanitizes sensitive data, compiles events into typed engineering artifacts, and serves this memory back to agents via push (hooks) and pull (MCP).
Related MCP server: ContextD
π― Supported Platforms
AgentRunlog acts as a non-intrusive context layer across the 4 major coding platforms:
Platform | Hooks registered | Context injection | Repeated-failure guard |
Claude Code |
|
|
|
Google Antigravity |
|
| stashed, delivered at next |
Cursor |
|
|
|
Codex CLI |
|
|
|
π Per-platform setup, behaviour and troubleshooting: docs/PLATFORM_GUIDE.md
ποΈ Architecture: The 3-Tier Karpathy Wiki
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β AGENT RUNTIME ENVIRONMENT β
β (Claude Code / Antigravity / Codex / Cursor) β
βββββββββββββββββββββ²βββββββββββββββββββββββββββββββββ¬ββββββββββββββββββββ
β β
Context Push / MCP Pull Hooks Capture (Thin Adapter)
β β
β [ Secrets Sanitization ]
β β
β βΌ
βββββββββββββββββββββ΄ββββββββββββββββββββ βββββββββββββββββββββββββββββ
β WIKI LAYER β β RAW LAYER β
β (.agentrunlog/wiki/) β β (.agentrunlog/raw/) β
β β β β
β βββ index.md (Module Map) β β β’ Immutable Transcripts β
β βββ decisions/ (Supersedes) ββββββ€ β’ Session JSONL Logs β
β βββ rca/ (Bug & Fixes) β β β’ Redacted Secrets β
β βββ dead-ends/ (Failed Trials) β βββββββββββββββββββββββββββββ
β βββ tasks/ (Work Log) β β²
βββββββββββββββββββββ²ββββββββββββββββββββ β
β Asynchronous Compiler
Periodic Linter (Deterministic Compiler)
(Staleness & Conflicts)raw/(Immutable Transcripts): Exact session dialogs and tool executions, stripped of API keys, tokens, and credentials before hitting disk.wiki/(Compiled Typed Memory): Structured, git-trackable Markdown records linked back to raw transcript evidence with confidence scores.schema.md(Strict Typing Contract): The exact specifications directing the compiler worker on how to classify and update knowledge.
π·οΈ Typed Engineering Memory
Unlike generic semantic vector stores that dump unstructured text, AgentRunlog organizes knowledge into strict engineering records:
βοΈ
Decision: Architecture and design decisions, trade-offs, andsupersedesrelations to prevent decision churn.π
RCA(Root Cause Analysis): Deep root-cause breakdowns of tricky bugs and verified resolutions.β
DeadEnd(Failed Attempts): Explicit records of approaches that failed, why they failed, and the conditions required to re-attempt.π
Task / Work Done: Chronological log of changes and feature completions.π§ͺ
Run: Benchmark, build, or test run outcomes verifying claims.
π How It Works
1. Push (Proactive Injection β ~30ms hook, Node-startup bound)
When a new agent session starts, AgentRunlog reads .agentrunlog/cache/active_context.json (< 5ms) and injects high-priority context:
Active architectural decisions (automatically excluding
supersededones).Known dead ends with explicit
retryConditions(Soft Guardrail β warns without blocking).Recent root cause analyses (RCAs) for fast failure recall.
A short handoff of the last session (open work) and the latest verified test/build/lint commands.
Strictly capped at 800 tokens to prevent context pollution.
2. Pull & Live Record (MCP Server)
Agents can actively query and record memory across workspaces (projectRoot) via native MCP tools:
search_runlog(query, types, module): Keyword & module-filtered search across decisions, RCAs, and dead ends.get_decision(id)/get_rca(id): Retrieve full context, rationale, evidence, and supersede graph.check_dead_ends(approach, module): Non-blocking Soft Guardrail check with retry conditions.get_active_context(): Instant pre-compiled project summary.record_decision/record_dead_end/record_rca: Autonomous live recording during active conversations.
3. Session Journeys
Every compiled session also gets a deterministic page, wiki/runs/<session>.md: what was asked, which files changed, which commands ran, and which errors were later resolved (failed command β passing run, with the files edited in between). Full text stays in raw/; the page points back by turn number. No model is involved.
4. Periodic Linting
The linter runs automatically after every compile/reindex (result in cache/lint.json, summarized by runlog report); runlog lint prints the full list on demand.
Flags records citing deleted or moved files (
STALE_CODE_REF,STALE_MODULE_REF); such records are also kept out of the push.Flags broken
supersedeslinks, superseded decisions still marked active, low-confidence active decisions, and dead ends without retry conditions.Optional, off by default β LLM decision-conflict review. Detecting a semantic contradiction between two active decisions needs a model. AgentRunlog never calls one itself, so this uses your coding agent's own model and spends your tokens. Enable it explicitly with
runlog llm-review enable(shows the cost warning and asks for confirmation;--yesto confirm non-interactively);runlog llm-review disableturns it off,statusshows the state. When on, the compiler deterministically picks up to 2 pairs of active decisions that touch the same module (~150β250 extra tokens per session) and the push asks your agent to compare them, ask you which one stands, and report via thereview_decision_conflictMCP tool (the loser becomessuperseded; "compatible" pairs are never asked again). The tool refuses to act while the feature is disabled.
Known limitation / planned improvement: candidates are currently chosen only by a shared affectsModules entry, so two decisions with no module set are never compared. A future version may also pick candidates by title/keyword similarity. That would catch more contradictions but would also raise false alarms and increase token spending (more pairs to review per session), so it will stay behind the same opt-in and consent.
5. Handoff, Guardrail & Verification (no model, no SessionEnd dependency)
Last session handoff and verified commands are pushed at session start (within the 800-token ceiling).
Repeated-failure guard: the 2nd failure of the same command in a session injects the known RCA / dead end on all four platforms, advisory only (see table).
Code sync: records whose cited files were all deleted are not pushed and are flagged by
lint/report.Claim check: "tests pass" claims without a passing run are flagged in the session journey and
report.Git link: commits made during a session are attached to its task and journey page.
Platform | Failure signal read | Advisory delivered via |
Claude Code |
|
|
Cursor |
|
|
Codex CLI |
|
|
Antigravity |
| stashed, then |
Platform notes: Antigravity cannot inject text from PostToolUse, so its advisory arrives at the next model call; Cursor's guard relies on the documented postToolUseFailure event; Codex requires hooks to be trusted once via /hooks. Details in docs/PLATFORM_GUIDE.md.
Compilation never depends on SessionEnd (not every Claude session fires it): it also runs after 25 uncompiled turns, on PreCompact, and at the next session start if a previous session left turns behind.
π Privacy & Safety First
Sanitization by Default: Regular expressions and pattern matchers strip credentials, bearer tokens, and private keys before anything is written to
raw/.Git Safety: Raw transcripts (
.agentrunlog/raw/) are excluded from Git via.gitignore. Only the curatedwiki/may be committed if team sharing is desired.Originals are never touched: past conversations are only read from each platform's own store. Only AgentRunlog's own copies in
.agentrunlog/raw/are ever replaced, and only after the new copy is fully written.No event loss, no truncation: hook payloads have no size cap and imported conversations are stored in full. A payload that cannot be parsed is logged to
cache/hook-errors.log, never silently dropped.Automatic history sync: on session start the hook refreshes past-conversation imports in the background (at most every 30 min); nothing to run by hand.
Opt-out & exclusions:
runlog pause/runlog resume(orprivacy.enabled=falseinconfig.json) stop all recording in a project;privacy.excludePatterns(globs) skip matching paths and commands.Non-blocking Execution: Hook adapters are dependency-free and small (~30ms, mostly Node startup), offloading compilation and extraction to background workers.
π€ Dual-Agent Design & Zero-Cost Offline Compiler
AgentRunlog makes an intentional architectural distinction between the Working Agent and the Compiler Worker:
Working Agent (Claude Code, Google Antigravity, Cursor, Codex): The primary AI coding assistant actively conversing with you, reading files, and writing code.
Compiler Worker (FR-10, NFR-06): An asynchronous background process that parses raw JSONL session logs to extract structured decisions, RCAs, and dead ends without polluting the working agent's context.
Why an Out-of-Band Compiler?
Forcing the working agent to simultaneously code and summarize hundreds of lines of chat history causes context bloat and mental fatigue (the primary pitfall observed in tools like Cline / Roo-Code). AgentRunlog offloads compilation to the background.
No model calls, ever:
All 4 supported coding platforms already run their own frontier LLMs, and AgentRunlog never talks to a model itself. Hooks capture what the user and the agent said and did (prompts, tool runs, errors, files); runlog compile extracts typed records from that work with deterministic pattern recognition, and the agent itself can record decisions through the MCP tools. No API keys, no network.
π Zero-Config Installation (One Command, All 4 Platforms)
AgentRunlog ships as a Universal Plugin Bundle (plugin.json, mcp_config.json, hooks.json, rules/, and skills/).
1. Install Globally (Auto-Configures All 4 Platforms via postinstall)
npm install -g git+https://github.com/trgysvc/AgentRunlog.gitEntry points: hooks run
bundle/hook.mjs(13 KB, no dependencies, ~30 ms); the MCP server is registered asbundle/agentrunlog.mjs, a self-contained single file that needs nonode_modules.dist/cli/index.jsis only therunlogcommand's entry. If the bundle is missing the installer falls back todist.
That's it! During global installation, postinstall automatically and non-destructively installs and configures all 4 platforms (you can also re-run runlog setup or runlog doctor anytime):
π£ Google Antigravity: Native plugin (
~/.gemini/config/plugins/agentrunlog/) with MCP, Hooks,rules/AGENTS.md, andSKILL.md.π Claude Code: Global MCP (
~/.claude.json), Hooks (~/.claude/settings.json), and Skill (~/.claude/skills/agentrunlog/).π΅ Cursor IDE & CLI: Global MCP (
~/.cursor/mcp.json), Hooks (~/.cursor/hooks.json), and Rules (~/.cursor/rules/agentrunlog.mdc).π’ OpenAI Codex CLI: Global MCP &
features.hooks = true(~/.codex/config.toml), Hooks (~/.codex/hooks.json), andAGENTS.md.
π οΈ How It Works Day-to-Day (100% Automatic)
You never need to remember runlog init, runlog compile, or "save this"!
Step 1: Just Open Any Project & Start Coding
Open any project (new or halfway built) in Antigravity, Claude Code, Cursor, or Codex and start chatting:
On the very first hook or MCP call, AgentRunlog automatically detects the project workspace, creates
.agentrunlog/, secures.gitignore, scans the codebase (package.json,git log,src/), and imports past conversations across all 4 platforms in the background!
Step 2: Work Normally (Zero User Effort)
You never need to say "save this" or "update memory". Simply talk to your AI agent and code naturally:
Silent Capture & Secret Redaction: Every prompt, tool run, and error is silently logged to
.agentrunlog/raw/via hooks, with API keys and passwords stripped before hitting disk.Autonomous Live Recording: When you naturally confirm a choice ("Let's use Drizzle ORM instead of Prisma"), the plugin rules instruct the agent to silently call
record_decisionin the background.History matching: Claude Code transcripts are matched to a project by their recorded
cwd, so a project never imports another project's conversations. A conversation keeps one record set (live and imported copies share the session id).Explicit vs. guessed decisions: decisions saved through
record_decisionare active immediately and survivereindex; decisions guessed from prompt keywords are alwaysdraftand never pushed.Automatic Session Compilation: After 25 uncompiled turns, on
PreCompact/SessionEnd, or at the next session start (crash recovery), the detached background compiler automatically extracts Decisions, RCAs, and repeated-failure Dead Ends into.agentrunlog/wiki/and updatesactive_context.json.
Step 3: Next Session (Automatic Memory Recall)
When you open a new chat tomorrow or switch between Claude Code, Antigravity, Cursor, and Codex:
Push: On the first turn, the hook injects active decisions, recent RCAs, and dead ends (< 800 tokens, ~30ms).
Pull: Before touching risky architecture, the agent automatically checks
check_dead_endsandsearch_runlogvia MCP so past mistakes are never repeated.
Step 4: Maintenance & Verification Commands
runlog doctor # Verify all 4 platform plugins + live MCP stdio handshake
runlog scan [--alias name] # Scan codebase + past conversations across all 4 platforms
runlog status # View active/superseded decisions, RCAs, dead ends, and token budget
runlog compile # Manually compile raw session transcripts into wiki pages
runlog lint # Audit wiki for stale file paths, missing retry conditions, or broken links
runlog usage # Disk space used by AgentRunlog, per folder
runlog scan --force # Re-import every past conversation (full text, never truncated)
runlog report # Impact report: sessions, injections, repeated failures, unverified claims, stale records
runlog pause # Stop recording in this project (runlog resume to continue)
runlog llm-review enable|disable|status # Opt-in conflict review by your agent's LLM (uses tokens, off by default)
runlog reindex # Wipe wiki and rebuild from scratch from raw/ transcripts (NFR-10)πΊοΈ Roadmap & Status
Core Engine: Typed record schemas (
schema.md), atomic disk storage, and two-layer sanitization filter.MCP Server: Local stdio MCP server with read (
search_runlog,get_decision,get_rca,check_dead_ends,get_active_context) and live write (record_decision,record_dead_end,record_rca) tools.Native Plugin Bundles: One-command Antigravity plugin installer (
runlog install-plugin) and Claude Code plugin manifests.Capture Adapters: Hook adapters for Claude Code, Google Antigravity, Cursor (own
.cursor/rules/agentrunlog.mdc, never overwrites.cursorrules), and Codex CLI.Handoff, verified commands, claim check, code sync, git link, repeated-failure guard on all four platforms (see section 5).
Impact report, disk usage, pause/resume, exclude patterns, automatic history sync.
Planned: broader conflict-candidate selection (title/keyword similarity) for the LLM review β more coverage, but more false alarms and higher token cost; will stay opt-in.
Automatic lint after every compile; opt-in (default off, token-cost consent) LLM decision-conflict review via the working agent.
Real-app verification of Cursor, Codex and Antigravity hooks (verified through the shipped hook with simulated payloads and the official docs; Claude Code verified end to end).
Codebase Bootstrap Scanner: Automatic project scan on
runlog init/runlog scanfor existing in-progress repos.Compiler Worker & Linter: Deterministic offline compiler,
active_context.jsoncache,wiki/index.mdbuilder,runlog lint, andrunlog reindex.
π License
MIT Β© Turgay SavacΔ±
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
This server cannot be deployed
Maintenance
Related MCP Connectors
Persistent engineering memory designed to follow developers across coding agents.
Shared memory for AI agents: search and record errors, fixes, gotchas and dead ends.
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Persistent long-term memory for AI agents: semantic search, knowledge graph, and task canvas.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides persistent, searchable memory and knowledge capture for AI-assisted development, enabling agents to retain decisions, bugs, and patterns across sessions and projects.265 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI coding agents to retrieve developer context, semantic memory, decisions, and checkpoints across sessions through hybrid full-text and vector search, with token-budgeted retrieval for task-relevant context.MIT
- AlicenseCqualityBmaintenanceEnables engineering agents to maintain persistent knowledge across sessions by storing decisions, invariants, gotchas, and rejected ideas, with staleness detection, conflict detection, full-text search, and structured context assembly.622MIT
- AlicenseAqualityCmaintenanceEnables coding agents to query a local, offline memory store of past session traces through hybrid BM25 plus semantic retrieval over extracted memories and chunks. Lets users recall relevant memories, search chunks and sessions, and explore cross-session clusters directly from their agent.31MIT