Termpolis

🧠 Meet Mneme — one memory, every agent, that learns as you work

Every AI session normally starts cold — you re-explain the task and burn 20–50K tokens reloading context. Mneme (named for the Greek muse of memory) is the local brain at the heart of Termpolis: one shared memory that Claude, Codex, Gemini, and Qwen all read and write, that remembers across sessions and learns from each one, so you stop repeating yourself.

• One memory, four agents. All four read and write the same store over the built-in MCP server. A fact one agent figures out is instantly recalled by the others — no copy-paste, no re-discovery.
• It learns from every session. When an agent finishes a chunk of work, Termpolis quietly distills the lesson — the fix, the decision, the gotcha — plus its own track record into the brain, so the fleet gets smarter the more you use it. Automatic for Claude, Codex, and Gemini (from their session transcripts); Qwen records its own.
• Every new agent starts warm. Open a fresh Codex or Gemini terminal and it already knows your project — the relevant memory loads at launch, behind the scenes, no wall of text.
• 100% local & private. Embeddings run in-process (bundled bge-small-en-v1.5, WASM) — no server, no telemetry, nothing leaves your machine. Optional at-rest encryption (AES-256-GCM) and conflict-free sync across machines via a folder you already sync.
• Built to trust. Content-addressed dedup (never stores the same thing twice), millisecond HNSW retrieval at scale, staleness-guarded recall, and an observable 🧠 Loaded N memories banner so you always know it fired.

Proven, not just claimed. A CI gate has one agent write a decision and a different agent recall it from a keyword-free paraphrase over the real MCP wire; semantic recall scores 0.97+ similarity on paraphrases. Backed by 7,000+ tests (97.5% statements / 98.5% lines).

The result: stop re-explaining context every session — and stop paying to reload it.

🆚 Why not just use Claude Code or Codex on their own?

Termpolis runs those exact CLIs, unchanged — and fixes the one thing they can't do alone: remember.

Same agents, same accounts you already pay for — Termpolis is the workspace around them that remembers and learns.

🛡 AI Security Center — what it actually does

Honest framing first. Any tool that lets you talk to a hosted model (Claude, Codex, Gemini, Qwen) is, by definition, sending your prompt to that provider. Termpolis cannot air-gap a prompt you choose to send, cannot guarantee a provider's stated retention policy is enforced server-side, and cannot stop a provider from later changing their terms. If your threat model requires those guarantees, run a local model — but accept the quality + hardware trade-off that comes with it.

What Termpolis can do is make the hosted path substantially safer than typing into a stock terminal, a browser, or a VS Code plug-in:

v1.25 moved the perimeter to the boundaries that actually leak. The secret engine used to watch exactly one of them — the keystrokes you send to an agent. It now also gates what a commit made through Termpolis captures, what a push made through Termpolis sends, and what gets written into the shared brain; an imported skill or MCP server is scanned before it is wired into an agent; and agent egress is judged against an allowlist rather than merely logged. Those gates — and the audit log — default to on, and an absent setting key keeps the secure default, so an existing install is protected on upgrade without touching Settings. Each can be turned off individually in Settings → AI Security; Safe Import lives in Settings → General.

v1.25.6 — three controls that were quietly not firing. Every one was found by writing a test against code nobody had tested. If you are on 1.25.5 or earlier, this is what was silently not protecting you:

• The GnuPG private-keyring rule could never fire. secring.gpg — your private keyring — had been grouped into the sensitive-file rule's own exclusion list beside the public keyrings, so the exclusion returned before the match could. A read of your private keyring was never flagged, and the failure mode was total silence, which reads exactly like "nothing happened". Only the pubring.* entries are excluded now.
• A NaN limit defeated the audit-log clamp and returned the entire log. typeof NaN === 'number' is true, so a NaN limit took the clamp arm rather than the 200 default — and Math.min/Math.max propagate NaN rather than clamping it, so the read degraded to "return everything", which is the one thing the 2,000-entry cap exists to prevent. The guard is Number.isFinite now.
• The Commit Shield reported repositories as PROTECTED after their hooks were removed. The protected-repo list was compared with a bare !==, and install stores either the renderer's cwd (forward slashes) or the native picker's OS-native path (backslashes) — so install-by-picker followed by uninstall-by-cwd never matched, and the repo stayed on the list with its hooks already gone. A security control that claims to be armed when it is not is worse than one that admits it is off. It is keyed on a canonical path now (Windows-only separator/case folding — a backslash is a legal filename character on POSIX, and folding it there would conflate two genuinely different repos).

Also fixed: the Strict-Mode Gemini refusal message never rendered on Windows. The banner was written to the PTY as a typed printf command, which only works on a shell that has printf — so on cmd.exe / PowerShell you got 'printf' is not recognized instead of the explanation, at the exact moment you most needed to know why the launch was refused. The block always worked; the message was what failed. It now goes straight to the renderer.

What this is and isn't: Termpolis is defense in depth for the hosted-model path — it raises the cost of accidental disclosure and gives you a record to audit. It is not a guarantee that source code cannot reach a provider — only not running the agent at all gives you that. The honest answer to "can a hosted model leak my code?" is "yes, if you send it; the question is whether the controls catch the obvious accidents and whether you trust the provider's terms for the rest." Termpolis is built for the engineers who've decided that trade-off is acceptable for the productivity hosted models give them.

See PRIVACY.md for the data-flow spec, TERMS.md for the Apache-2.0 / "AS IS" disclaimer.

🧠 Shared memory — the deep dive

The moat above in full — every capability of the brain that all four agents share:

• One memory, four agents. Claude, Codex, Gemini, and Qwen all read and write the same store over the built-in MCP server (memory_search / memory_write / memory_list / memory_primer). A fact one agent figures out is instantly available to the others — no copy-paste, no re-discovery.
• It survives quitting the app. Stored as plain JSONL (swarm-memory.jsonl) in Termpolis's per-user app-data folder — %APPDATA%\termpolis\ on Windows, ~/Library/Application Support/termpolis/ on macOS, ~/.config/termpolis/ on Linux — and reloaded with its embeddings at startup. Because it lives in your user profile (not the install folder), it survives app updates and even an uninstall/reinstall — close Termpolis, reopen it tomorrow, the context is still there.
• It can follow you across machines (optional). Point the brain at a folder you already sync — Dropbox, OneDrive, iCloud Drive, Google Drive, Syncthing, or a git repo — and the same memory shows up on every computer. It rides the local synced folder their desktop client maintains (no provider API, no OAuth), so each machine writes its own shard file: there are never sync conflicts; the stores merge conflict-free (a content-hash-deduped grow-only set) and deletes propagate as tombstones. (Google Drive: use mirror mode so files stay on disk, not online-only.) No Termpolis server, no new account. Off by default; enable it in the Memory panel. Optionally encrypt it at rest with a passphrase (AES-256-GCM, key in the OS keychain) so the cloud provider only ever sees ciphertext — enter the same passphrase on each device to unlock.
• It feeds itself. A background indexer ingests your past Claude / Codex / Gemini transcripts automatically (10 s after launch, then every 30 min). Idempotent (content-hash dedup), so it only ever embeds genuinely new content — no action required from you.
• Fully offline, no server, no secrets. Embeddings run in-process via WASM with a bundled bge-small-en-v1.5 model — no Ollama, no native binaries, nothing leaves your machine. The indexer reuses the same sensitive-file denylist as the read watcher, so .env files, keys, and cloud credentials are never embedded.
• Scales into six figures. Vectors are packed into a typed-array store (about half the RAM of boxed arrays), and past tens of thousands of entries an HNSW approximate-nearest-neighbour index engages automatically so search stays sub-linear (a few ms/query, measured). The graph lives off the JS heap and persists to disk. It builds once, lazily, in the background without blocking your searches — the first query after the store crosses the threshold returns instantly from the exact fallback while the index builds (frame-budgeted so the UI never stalls); every later search and launch uses the saved graph.
• Auto-recovers from compaction. When Claude Code compacts its conversation to fit the context window, it summarizes detail away — but that detail still lives in the brain. Termpolis watches the terminal, waits for the compaction to settle (debounced through the whole thing), and re-adds a one-line memory pointer to the agent's input — ready to send, never auto-submitted — so the agent reloads what it lost behind the scenes over MCP (memory_primer) instead of a wall of pasted text. Cooldown-guarded to fire once per compaction; opt-out in Settings. Your durable memory is the large working set; the model's window only holds the active task.
• See compaction coming. A live context-pressure pill in the status bar shows how full the focused agent's window is — healthy → filling up → nearly full → compaction imminent — from real token counts when the agent reports them (Claude's token_update stream) or a clearly-labeled heuristic otherwise. So you watch the pressure build and know recovery is handled, instead of being surprised by a compaction.
• You can see it working — and trust what it returns (v1.16.7). Memory used to load invisibly, so a successful recall looked identical to no recall at all. Now every primed launch shows a banner — 🧠 Loaded N memories for "<project>" on success, or a clear ⚠️ Memory recall unavailable if the brain couldn't be reached — so you always know whether context loaded. Four reliability fixes back it up: a fast indexer tier makes your current conversation searchable within seconds instead of waiting for the next 30-minute pass; recall flags any code reference whose file has since been deleted as ⚠ STALE — verify before use instead of asserting it as fact; the memory hook resolves an absolute Node path so it still fires under thin-PATH login shells (NVM and friends); and an adaptive relevance floor keeps weak, off-topic hits out of the digest entirely — the agent gets the relevant slice, never padding.

How it works:

1. Capture — your on-disk AI transcripts are parsed (tool-call / reasoning / system-prompt noise stripped) and split into chunks.
2. Embed — each chunk becomes a 384-dim vector locally, in-process, via onnxruntime-web (WASM).
3. Store — chunks + vectors persist in a durable on-disk log, deduplicated by content hash so re-indexing is cheap; vectors are packed into a typed-array store and indexed with HNSW once the brain grows large.
4. Recall — any agent calls memory_search over MCP and gets the most relevant past context back, blending semantic vector search with keyword matching.

The result: stop re-explaining context every session, and stop paying to reload it.

Controls — open the Memory panel (Ctrl+Shift+M, or the Command Palette → "Memory") to see what's remembered (chunk count), search it, feed it on demand ("Index past conversations" / "Index this repo's code"), inject the most relevant context into the active agent with one click, and turn on cross-machine sync (point it at a synced folder). Launched agents are also auto-primed with the project's relevant context (toggle in Settings): a one-line note in the agent's input points it at the memory_primer MCP tool, so the digest loads behind the scenes — no giant dump on the terminal — and the agent holds it as background instead of acting on it or resuming old work uninvited. Context from the current directory's project comes first (its past conversations, then its code/notes), and anything recalled from other projects is clearly labeled as possibly not applying.

🕸 The Weave — one fabric across memory, code, and every repo (v1.23)

v1.23 "The Weave" turns the shared brain and the code graph into a single, self-weaving fabric. Recall no longer stops at text — it points at the code a lesson is about — and the non-obvious connections across your whole workspace are drawn ahead of time, so agents reason faster.

• Memory ↔ code bridge. Stored lessons and decisions now carry structured code anchors (file + symbol), so recall can cross straight from "this is how we fixed the auth bug" to the exact function it lives in — and, in reverse, from a function to everything the brain knows about it. The two stores used to be islands; now they're joined by a shared key.
• Predict where to fix it — code_locate. Give it an error or a problem description and it returns a ranked list of {file, symbol, why: [past lessons]} — the code sites most likely responsible, each with the fixes and decisions that point there. It's exposed as an MCP tool, so any agent can reach for it first when debugging instead of grepping blindly. (The bridge fills in over time: why gets richer as new lessons are anchored and the background weaver backfills older ones.)
• The Weave — an always-on background connection-miner (flagship). While you're idle, a weaver continuously draws connections across the entire unified brain: cross-repo code-structure analogies (a pattern in one repo that echoes one in another), cross-repo answer/decision analogies, and the memory↔code bridge edges above — materialized ahead of time with provenance and a weight floor so the graph stays high-signal. The connections are already there when an agent needs them.
• Per-repo, durable code graph. The code graph is now keyed per repository — a second repo no longer clobbers the first, and each repo's graph is a durable on-disk store, so a transient non-git directory (or git off the PATH) won't wipe one you've already built.
• Automatic bug → fix edges. When a task with a problem finishes, Mneme now mints the causal solves edge automatically, so "this error → that fix" is traversable later without anyone hand-linking it.
• Rock-solid, never-delete memory. Idle consolidation moves aged memories to a cold-archive tier instead of deleting them — nothing curated is ever lost — and deep recall can still reach archived entries and history beyond the hot search window. Cross-repo transfer is relevance-scoped, so one unified brain gives cross-project reuse without the noise.
• Sharper learning. An opt-in LLM distiller (TERMPOLIS_MNEME_DISTILLER=1) writes richer, more precise lessons; memory_related is now undirected, so a connection surfaces from either end.
• The explains edge — the code ↔ purpose bridge (v1.25). A semantic memory now links directly to the code chunk it explains, so the prose that says why a thing works the way it does hangs off the code itself. The edge is gated on both embedding similarity and a shared file/symbol anchor — a merely chatty neighbour can never claim to explain code it has no anchor into. In the same pass the weaver was fixed to actually mint what it mined: intra-repo analogies are now allowed (it was cross-repo only, so the most useful connections — the ones inside the repo you're in — were being discarded), and the similarity floor drops 0.82 → 0.72.

🆚 How Termpolis improves on other AI harnesses

Termpolis doesn't replace Claude Code, Codex, Gemini CLI, or Qwen Code — it runs them, unchanged, and adds the layer they're all missing. A bare AI CLI (or an IDE assistant like Cursor or Copilot) is a single vendor's model talking to a single session: no memory of yesterday, no awareness of the other tools you use, and no guardrail on what leaves your machine. Termpolis turns that into a coordinated, persistent, auditable workspace.

The short version: other harnesses optimize a single agent's loop. Termpolis optimizes your whole agent fleet — giving four competing models one shared, durable, trustworthy memory (hardened in v1.16.7 so a working recall is visible, fresh, and never cites a file that no longer exists), a security perimeter around the hosted-model path, and a single place to watch and review everything they do. See the full, sourced feature-by-feature comparison vs Warp, Wave, JetBrains Air, and Tabby.

🔀 Second Opinion — a different agent double-checks the last answer

Every model has blind spots. Second Opinion hands the most recent answer in any AI terminal to a different agent for a fast, read-only critique — the feedback is pasted back into the same terminal, ready for you to send to your primary agent or just read and discard.

• Pick any installed agent. A Second Opinion dropdown on each AI terminal lists exactly the agents you have installed — OpenAI Codex, Gemini, Qwen — with Claude and its models (Fable · Opus · Sonnet · Haiku) nested underneath. So while you're driving Opus, you can have Fable — or Codex, or Gemini — sanity-check the last solution.
• It reviews the real, recent work. Termpolis captures the terminal's most recent output, asks the chosen agent to review the latest solution/answer/approach, and injects its concise feedback back into your terminal as an unsent block — you decide whether to act on it.
• Read-only by design. A review needs no file access, so it runs the agent in one-shot headless mode — nothing it says touches your repo. The captured text is passed out-of-band (never on a command line), so a prompt scraped from your terminal can't inject a command.
• Only what's installed shows up, and it appears only on AI terminals. Gemini runs through the Antigravity CLI (agy), its current headless entry point.

Proven end-to-end. A CI test drives a real review from Claude, Codex, and Gemini (via agy) against a deliberately-bad solution ("sort 1,000,000 items with bubble sort") and confirms each returns substantive feedback.

⚡ Token Headroom — compress what Claude Code sends, cut your burn rate (v1.29)

Long AI coding sessions chew through rate limits and hit compaction fast — and the biggest culprit isn't your prompts, it's the file reads, command output, and pasted screenshots the agent ships back to the model on every turn. Token Headroom compresses that traffic before it reaches Anthropic, so you get more work done per session before you hit a wall.

• Always on for Claude Code. Every Claude session launches through a local, off-thread compression proxy (its own process — never the UI/PTY thread). No toggle, no setup. If the proxy is ever unhealthy the launch silently goes direct, and a live session self-heals when the proxy recovers — so a proxy hiccup costs you compression, not your agent.
• It compresses what actually costs you. Verbose Bash/command output, large file Reads, and pasted images (downscaled below the model's cap) are shrunk deterministically. Nothing is lost — the agent calls the retrieve_full tool to pull any compressed result back in full when it needs the detail.
• Prompt-cache safe — proven. Naive compression busts Anthropic's prompt cache and costs you more. Headroom compresses deterministically, so re-sent history stays byte-identical and the cache keeps hitting. Measured on a real multi-turn session: ~50% fewer tokens ingested per turn with cache hits fully preserved.
• Your memory/brain is never touched. Compression lives only on the outbound wire to Anthropic; the shared memory store, recall, and learning are untouched.
• See the receipt. Settings → Token Savings shows the live % of tokens saved (session + all-time), by type, plus prompt-cache health — computed from Anthropic's real usage numbers, on your machine.

Built in-house, tested hard. Deterministic compressors, a source-level cache-safety guard, fail-open at every layer, and an end-to-end proof measuring real token reduction with the cache intact — all under Termpolis's 7,000+ test suite.

📊 Memory & Learning dashboard — proof it's working, computed locally

A Memory & Learning tab in Settings turns the brain from a black box into an inspectable instrument — every number computed on your machine, offline, from the append-only store. No word-taking; nothing on the screen leaves your machine.

• Vector memory — int8 quantization, and a straight answer about whether you want it. Your embeddings live in the main process — the same thread that pumps the PTY — so storing them as int8 instead of exact floats is 4× less vector RAM. But a bare switch would be a trap — nobody can answer "should I enable int8 quantization?" in the abstract — so this is a decision aid, and the answer it gives almost everyone is don't: at a typical corpus (14k vectors ≈ 21 MB) it says "not needed — turning int8 on would free about 16 MB, which is not enough to change anything." A control that only ever markets itself is an upsell, not a tool. Off by default. Settings → Memory & Learning.
• What's stored — memories by cognitive type (episodic · semantic · procedural · entity · summary) and by which agent authored them.
• Live knowledge graph — a force-directed view of the real typed edges recall walks (bug → fix → what superseded it), colored by type.
• Code connections (v1.25) — the structural code graph (symbols, and the caller/callee edges between them) now has a tile of its own. Indexing a repo was already minting thousands of these edges into a store the dashboard simply never read — so "connections" looked empty while the graph underneath was full.
• Competence, calibrated from real work (v1.25) — per-domain self-competence now learns from what actually happened: a landed commit and a passing or failing test run both feed the calibration. It previously only fired on a completed swarm task, so for most people every domain sat at zero attempts and the panel stayed blank forever. A failing suite is what finally calibrates confidence down.
• Learning over time — cumulative growth of the store and the distilled lessons within it.
• Reliability SLIs — recall-fired rate, embedder availability, write durability, and typical (median) recall latency. (v1.25.6: a UI search that had fallen back to keyword — because the embedder was down — was still being booked as a vector recall, so the dashboard over-counted them. It reports the path that actually ran now. A proof dashboard that flatters itself is worse than no dashboard.)
• Model portability & cross-agent learning — which agents authored what, and where a lesson one agent learned was later reused by another.
• Receipts — recalls served, solutions reused, and estimated tokens saved.

These numbers are read when you open the tab and when you press Refresh — never on a timer (v1.25.16). Computing them means scanning the whole store, and that scan runs in the main process, which is the same thread that echoes your keystrokes into the PTY. On a 5-second poll it stalled typing every 5 seconds and generated enough garbage to drive the very GC pauses the dashboard used to display. A dashboard paid for out of your typing latency is not worth having. The freeze history that used to sit above this section is gone for a worse version of the same reason — see Diagnostics that cost more than they're worth, below.

On int8, two guarantees worth stating plainly. Recall parity against the exact-float baseline is benchmarked and CI-gated — the benchmark scores the quantized store against the same committed baseline as the float one on the real bge model, and recall@10 is identical; a change that degraded it would fail the build. And it is losslessly reversible: the JSONL on disk always keeps exact floats, so int8 is purely an in-RAM representation, never a data migration. Turning it off restores full precision — nothing is ever destroyed.

The screenshot shows the dashboard's layout with representative sample data; your instance fills in with your own local numbers as you work.

Diagnostics that cost more than they're worth (removed in v1.25.16)

v1.25.15 shipped a V8 sampling profiler so that a freeze in unlabelled code could still be named. The reasoning was sound and the measurement was not: Profiler.stop was clocked at 4–15 ms in a small test script, so it was called straight from the stall watchdog. In a real main process — 1.1 GB heap, 1.75 GB RSS, an enormous loaded-code fo