RunawayContext

RunawayContext

Persistent context for any AI agent — with rules that hold themselves.

[](LICENSE) [](pyproject.toml) [](CHANGELOG.md) [](.github/workflows/ci.yml) [](pyproject.toml) [](docs/HARDRULES.md#hr-1--no-network-egress-by-default-ever-at-any-tier) [](docs/HARDRULES.md)

If you've explained the same project to your AI four times this week, this is for you. RunawayContext is a small Python library, CLI, and MCP server that gives any AI agent durable memory across sessions, projects, environments, users, and machines — coding assistants, custom Python agents, internal orchestration, enterprise workflows, customer-service bots. The architecture has rules; every rule has a test; the build won't ship if a rule drifts.

And it keeps your context window mostly empty. The always-loaded surface stays ≤3,000 tokens regardless of how much you've taught it — usually a 70–95% reduction versus the giant instruction files most adopters are coming from. Deep knowledge lives in a SQLite database and retrieves only when the AI actually needs it.

[The problem](#the-problem-we-kept-hitting) · [What it is](#what-it-is) · [How it works](#how-it-works) · [Pick a tier](#the-six-rung-ladder) · [Install](#install--your-ai-does-it) · [Undo](#dont-like-it-the-undo-path)

---

The problem we kept hitting

Every AI session starts from zero. You explain the project, the conventions, the gotchas, the people involved, the systems it integrates with. The AI nods, helps for an hour, then "forgets" by next session. You write a bigger and bigger rules file. The rules file itself starts eating your context window. The AI starts ignoring half of it. Six months later you're back to square one — except now you also have a 2,000-line instruction file that drifted out of alignment with what the agent is actually doing.

This is just as true for a coding session as it is for an enterprise automation agent or an internal customer-service bot — anywhere you have an AI that needs to remember "we tried that, it didn't work, going forward do X" and yet your only handle on its memory is a giant prompt or an instruction file that grew organically.

flowchart LR
    A[Start a session] --> B[AI loads 5-60K tokensof rules]
    B --> C[Context window fills]
    C --> D[AI forgets mid-session]
    D --> E[You correct itfor the 4th time]
    E --> F[You add another bulletto the rules file]
    F --> G[File grows past 2000 lines]
    G --> H[AI now ignores half of it]
    H --> A

The naive fix — one giant instruction file — creates its own problems. The harder problem is that even disciplined people drift. Every session adds a "while I'm here, let me note this." Six months later the rules file is bloated, internally inconsistent, and quietly stops being enforced.

RunawayContext solves both. The always-loaded surface stays under 3,000 tokens regardless of how much knowledge you've accumulated. The discipline is enforced in code, not policy — the regenerator literally refuses to write briefs past their line cap. The deep knowledge lives in a SQLite database with full-text search and retrieves on demand.

---

What it is

RunawayContext is a small Python library + CLI + MCP server that gives any AI agent a structured memory across sessions, projects, environments, machines, and humans — without growing into the giant rules file you're trying to escape.

What "any AI agent" means in practice:

• AI coding assistants — Claude Code, Cursor, Copilot, Aider, Windsurf, Codex CLI. They read project briefs and call MCP tools mid-conversation.
• Custom Python agents — anything that imports runaway_context.Client and calls log_lesson(...), search_lessons(...), propose_knowledge(...). No LLM required by the library itself.
• Internal AI workflows — in-house orchestration agents, n8n flows, Temporal workers, queue consumers. Any process that needs durable, queryable project knowledge between runs.
• Enterprise / customer-service bots — agents that need persistent knowledge of their environment, their users, and the scar-tissue lessons learned across past interactions.
• Anything that reads markdown — even with no integration code, RunawayContext can write a per-project brief to a file your agent already reads.

Four things make it tick:

• Local-first. Zero network calls by default at every tier. Your knowledge stays on your disk.
• Tier-progressive. Start with a paste-once markdown template (T0). Grow into a 13-tool MCP server with semantic retrieval, lifecycle-aware lessons, and audit-log governance (T5). You only enable what you need.
• The rules hold themselves. Fifteen named rules (HR-1 through HR-15), each with a machine-checkable test. The discipline isn't a "be careful" line in the docs — it's code that fails the build the moment a rule drifts.
• AI-native install. Paste a prompt to your AI. It clones the repo, runs the test suite, runs diagnostics, walks a tier decision tree with you, and reports honestly. No hand-holding required.

> Built by people who got tired of repeating themselves to their AI. v1 launched April 2026 as a single-file release; v2 added split DBs, write guards, and a drift detector; v3 (this release) adds the 15 hard rules with named tests, the AI-native install loop, the MCP server, lifecycle-aware lessons, and a kind undo path. The reference implementation grew up driving enterprise-system integrations and an in-house AI orchestration agent — none of which are "coding assistants" in the classic sense.

---

How it works

flowchart LR
    AI["Your AI agent(coding tool, custom bot,internal workflow, etc.)"]
    MCP["RunawayContext(MCP / CLI / Python Client)"]
    DB[("knowledge.db+ sessions.db")]
    BRIEF["Per-project brief≤150 lines"]

    AI -- "what should I know?" --> MCP
    MCP -- "≤3K-token brief" --> AI
    AI -- "log this lesson" --> MCP
    AI -- "search this topic" --> MCP
    MCP -- "FTS5 + optional vec0" --> DB
    DB -- "on-demand retrieval" --> MCP
    MCP -- "regenerate on update" --> BRIEF
    BRIEF -- "loaded on project entry" --> AI

The flow has three sides, and each one is small on purpose.

Your AI's view is a brief — a short markdown file written by the regenerator. When the agent enters a project, the brief loads automatically. Coding tools read it where they already look (Claude Code reads CLAUDE.md, Cursor reads .cursor/rules/, Copilot reads .github/copilot-instructions.md). Custom Python agents call Client.get_brief(project) directly. Internal workflows include the brief in their system prompt. Either way, the brief contains the project's top warnings, active lessons, active references, and pointers into the database for everything else. It's capped at 150 lines and the regenerator refuses to write past that cap.

The database holds the deep knowledge: every lesson-learned, every reference chunk, every project manifest, every audit-log entry, every brief snapshot. It's SQLite with FTS5, project-tagged on every write, soft-delete-only, with a six-state maturation curve so old lessons drop out of briefs but stay queryable. Optional sqlite-vec integration adds vector retrieval on top of FTS5.

The integration surface is whichever fits your AI. The MCP server (runaway mcp serve) is the canonical path for clients that speak the Model Context Protocol — Claude Code, Cursor, custom MCP clients. The Python Client class is the canonical path for in-process agents, scheduled jobs, and orchestration code (from runaway_context import Client). The CLI (runaway log-lesson ..., runaway search ...) is the canonical path for shell scripts, n8n / Temporal nodes, and anywhere a subprocess is cleaner than a library import. All three surfaces enforce the same hard rules.

A typical interaction: the agent calls search_chunks("retry policy") mid-task and gets the relevant references. It calls propose_lesson_draft(...) when it notices scar tissue ("we got burned by X — going forward, do Y"). The draft sits in an inbox until a human approves it, so the AI cannot unilaterally bloat your knowledge base.

The whole loop is measured. Telemetry records retrieval latency, brief sizes, drift findings — local-only, never network. Drift detection runs every 10 minutes (cron) or on every session end (Stop hook), warning you when any always-loaded file grows past its cap.

---

The token math

The architectural payoff is concrete: instead of loading every rule, convention, and gotcha on every session, your AI loads a small per-project brief plus pointers — and queries the database when it needs more.

A typical before / after on a single session start:

| Approach | Tokens loaded each session | Notes | |---|---|---| | Single CLAUDE.md at 500 lines | ~3,500 | Fine for now; will grow | | Single CLAUDE.md at 2,000 lines | ~13,000 | Eating a real slice of your context window | | CLAUDE.md + AGENTS.md + .cursorrules + inline pasted notes | ~16,000–60,000 | Common in the wild; often duplicated | | Multi-project switcher across 5 projects, naive | ~25,000+ | Project A's rules pollute Project B's session | | RunawayContext | ≤3,000 | Constant. The brief is line-capped (HR-5); the regenerator refuses to write past 150 lines. |

The bigger your knowledge corpus grows, the bigger the win — because RunawayContext loads a top-warnings + active-lessons brief at the top of each session, and your AI pulls the rest on demand through FTS5 (and optional sqlite-vec) when it actually needs it.

A worked example. A T2 install with 200 logged lessons and 500 reference chunks weighs about 4.5 MB on disk. A naive instruction-file approach holding equivalent content would be ~280K tokens — far past any current model's context window. RunawayContext loads 1,800–2,400 tokens at session start; the AI calls search_lessons("...") mid-task to pull what it needs. The 280K tokens still exist, but they're in knowledge.db, not your context window.

Said another way: you stop paying tokens for knowledge the AI doesn't need right now.

---

Why v3 exists — the evolution

| Version | Released | What changed | Why | |---|---|---|---| | v1 | 2026-04-03 | First public release as "SuperContext"; single-file SQLite layout; 4-tier knowledge architecture defined as policy. | Proved the model. | | v1.1 | 2026-04-07 | Renamed to RunawayContext. Added runaway-loop safeguards (token-budget caps, attempt limits) after a fuzzy-approval loop burned a third of a week's tokens. | Real incidents reshape the design. | | v2.0 | 2026-05-04 | Split DBs (knowledge.db + sessions.db), required project tagging on every write, drift detector, auto-generated briefs, multi-user setup helper. | v1's policy-only discipline drifted in real-world use. v2 moved the discipline into the schema and the regenerator. | | v2.0.1 | 2026-05-06 | Documentation tightening: closed a loophole where "optional detail files" in Tier 2 could re-introduce the bloat v2 was meant to prevent. | The spec must say what it means; ambiguity is a loophole. | | v3.0 | this release | Fifteen hard rules (HR-1..HR-15) each with a named test, AI-native install loop, 13-tool MCP server, six-state maturation curve, three-axis severity, slug lifecycle, trigger-based lesson capture, hash-chained audit log, environment doctor, kind undo path. | v2 enforced discipline. v3 enforces the architecture itself — every claim has a named test; loopholes are closed by construction. |

The architectural goal hasn't changed since v1: minimize the always-loaded surface, route retrieval intelligently, keep the system honest over time. What changed is how the honesty is enforced. In v3, every rule has a named test; every test must pass for the release to ship. The system polices itself.

---

The six-rung ladder

You don't have to "set up RunawayContext." You pick a rung and grow into the next one when your situation outgrows it. Click any tier to expand its details.

T0 — Hello World  —  You haven't logged anything yet. Markdown-only, no install.

flowchart LR
    YOU[You] -- "paste RETRIEVAL.mdinto your project" --> PROJ[Project root]
    PROJ -- "reference from CLAUDE.md /.cursorrules / AGENTS.md" --> AI[Your AI]
    AI -- "follows the template" --> AI

Who: anyone who wants a sane starting point but isn't ready to install anything.

What's on: a single markdown template (RETRIEVAL.md) you copy into your project root and reference from your AI tool's instructions file.

What's off: everything else. No DB, no Python, no install footprint.

Resource budget: ~50 KB on disk, 0 MB RAM, 0 bytes network.

Promotion gate to T1: you've accumulated 5+ project-specific notes manually and want them searchable.

Rollback: delete the markdown file. Done.

T1 — Solo  —  Single developer, one machine. Full DB, no MCP.

flowchart LR
    AI[Your AI] --> CLI[runaway CLI]
    CLI --> KDB[("knowledge.dbFTS5 + write guards")]
    CLI --> SDB[("sessions.dbtranscripts")]
    CLI --> BRIEF["Per-project briefsauto-generated, ≤150 lines"]
    KDB -.-> DRIFT["Drift detectorStop hook / cron"]
    DRIFT -.-> YOU[You]

Who: a single developer on one machine.

What's on: the full v2 surface — knowledge.db + sessions.db, FTS5 search, project-tagged write guards (HR-2), auto-generated briefs with PRESERVE_START/END blocks for hand-curated content, drift detection on session end.

What's off: MCP, telemetry, semantic retrieval, record versioning, audit log.

Resource budget: ~80 MB RAM during CLI invocations; ~150 MB disk steady-state; 0 bytes network.

Promotion gate to T2: install has been used for ≥30 days, ≥10 lessons across ≥2 projects, ≥1 drift warning logged.

Rollback: disable T2+ features in config; T1 capabilities stay intact.

T2 — Solo Power  —  Active multi-project developer. The most common starting point.

flowchart LR
    AI[Your AI] -- "MCP stdioContent-Length framing" --> MCP[runaway mcp serve]
    MCP --> KDB[("knowledge.db+ embedding sidecar")]
    MCP --> SDB[(sessions.db)]
    MCP --> METRICS[(metrics.db)]
    AI -- "propose_lesson_draft" --> DRAFTS[Drafts inbox]
    DRAFTS -- "you approve" --> KDB
    KDB --> SPEC[Specialist agents]
    KDB --> CROSS["Cross-system data map(your ERP, CRM, project mgmt, ...)"]

Who: an active multi-project solo developer who wants their AI integrated via MCP.

What's on: T1 plus the 13-tool MCP server, local telemetry (never network), record versioning + soft-delete, predictive drift rules, multi-project stacking, optional semantic retrieval (FTS5 + sqlite-vec), specialist agents, cross-system data map, trigger-based lesson capture via propose_lesson_draft, six-state maturation curve, three-axis severity, slug lifecycle (alias / deprecate / merge), brief preview/rollback, runaway stats dashboard.

What's off: team-mode features (attribution exports, federation, SSO, multi-tenant rollout).

Resource budget: ~150 MB RAM with MCP + embedding model resident; ~250 MB disk; 0 bytes network default.

Promotion gate to T3: a second author_id has logged at least one approved lesson in the last 30 days.

Rollback: drop the second user's overlay; return to single-user knowledge.db. Schema columns for T3 stay present (HR-4 non-destructive) but unused.

T3 — Pair / Squad  —  2–5 collaborators sharing a knowledge repo.

flowchart LR
    A1[Author A] --> KDB1[("local knowledge.db")]
    A2[Author B] --> KDB2[("local knowledge.db")]
    KDB1 -- "runaway export --output ..." --> REPO["Team knowledge-repo(JSON in git)"]
    KDB2 -- "runaway export --output ..." --> REPO
    REPO -- "runaway importconflict reporter" --> KDB1
    REPO --> KDB2

Who: 2 to 5 collaborators sharing one install — whether that's a codeba

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sms021
• Source: sms021/RunawayContext
• License: MIT
• Homepage: https://RunawayIdeas.net

Install and usage instructions live in the source repository linked above.