[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_109":110},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":-5,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":48,"_57":58,"_59":60,"_61":-5,"_62":-5,"_63":-5,"_64":-5,"_65":66,"_67":68,"_69":70,"_71":72,"_73":74,"_75":-5,"_76":-5,"_77":-5,"_78":48,"_79":-5,"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91},"apiUrl","https://odel.app/api","creator","drexthealpha","moduleId","knos","@drexthealpha/knos","displayName","Knos","tagline","One local memory every coding agent on this machine shares, with claims so they don't collide.","iconKey","https://avatars.githubusercontent.com/u/142920951?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1788410547000,"updatedAt",1788669504000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.drexthealpha%2Fknos","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",1,"upstreamUpdatedAt",1788655957000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/drexthealpha/Knos","githubRepoFullName","drexthealpha/Knos","releaseId","ext-drexthealpha-knos","version","0.1.5","descriptionMarkdown","# Knos\n\n\n\n[![Knos MCP server](https://glama.ai/mcp/servers/drexthealpha/Knos/badges/score.svg)](https://glama.ai/mcp/servers/drexthealpha/Knos)\n\n**Coordination for repos with more than one agent in them. Two contributors,\nor two agents, change the same thing without knowing it. Knos is the record\nof who is on what — and it refuses to answer about work somebody else has\nalready taken.**\n\nTake it in whichever shape you already wanted. **Nothing here asks you to\ninstall Knos to try it.**\n\n## Start here: the Action\n\nZero install for the repo. One file, no dependency added to your project, and\nit never fails a build:\n\n```yaml\n# .github/workflows/knos-claims.yml\non: [pull_request]\npermissions: { contents: read, pull-requests: write }\njobs:\n claims:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: drexthealpha/Knos/action@v0.1.6\n```\n\nThat is the whole of it. It reads `.knos/decisions.md` — an ordinary file\ncommitted to your repo — and comments on a pull request when the branch\ntouches work somebody has claimed, or a decision already recorded. Nothing is\nblocked and nothing is required: **it exits 0 on every path, including every\nfailure path and every unexpected one**\n([`tests/test_shared_repo.py -k never_returns_non_zero`](https://github.com/drexthealpha/Knos/blob/main/tests/test_shared_repo.py)).\n\nThe tag is pinned rather than a branch, so what runs in your CI is a fixed\nfile you can read first: `git show v0.1.6:action/knos_pr_check.py`. It is\nstandard library only. You can watch it having run rather than take this on\ntrust — it fired on\n[pull request #1](https://github.com/drexthealpha/Knos/pull/1) here, matched a\nstanding claim, named who held it, and exited 0.\n\n**Agents are optional.** The file can be written by hand. If nobody on the\nrepo ever runs an agent, the Action still tells two humans they are about to\nland the same change twice.\n\n## Or embed it: the claim, as a library\n\nIf you would rather have the behaviour inside the tool you already ship than\nrun anything of ours, import it. No MCP, no CLI, no daemon:\n\n```python\nfrom knos.core import Claims\n\nwith Claims(repo=\".\", who=\"my-agent\") as claims:\n taken, holder = claims.take(\"the risk guard\")\n if not taken:\n return claims.withheld(\"the risk guard\") # the refusal, in words\n```\n\n`take` is the compare-and-swap that lets exactly one of two agents win the\nsame work in the same second. The hold is bound to the session you pass, not\nto the name — an agent that calls itself the holder is still refused. Claims\nlapse on their own after 30 minutes, so a crashed agent cannot hold work for\never. [`src/knos/core.py`](https://github.com/drexthealpha/Knos/blob/main/src/knos/core.py),\n[`tests/test_core.py`](https://github.com/drexthealpha/Knos/blob/main/tests/test_core.py).\n\n**This is the preferred way to adopt Knos.** Native inside your tool, or the\nAction in your repo. The standalone server below is the third option, not the\nfirst one.\n\n## Or run it as a server, if you already run several agents\n\n`pip install knos && knos connect` puts it in front of Claude Code, Claude\nDesktop, Cursor and OpenCode as an MCP server, and `knos guard --install`\nmakes the refusal reach the edit itself. That is the power-user path and it is\ndocumented in full further down; it is worth it when you personally have three\nagents open on one tree, and overkill when you do not.\n\n## Judging this in five minutes\n\n[**docs/JUDGE_GUIDE.md**](https://github.com/drexthealpha/Knos/blob/main/docs/JUDGE_GUIDE.md) maps every claim to a file, a\ntest or a live artifact, and states the limits plainly.\n[**docs/VERIFICATION.md**](https://github.com/drexthealpha/Knos/blob/main/docs/VERIFICATION.md) is the same list with the\ncommands and explorer links that settle each one.\n\nThe whole argument is one command:\n\n```bash\npython scripts/ablation.py\n```\n\n| Arm | Store present | Store deleted |\n|---|---|---|\n| **Spend: the same request a second time** | **paid again 0/12** | **paid again 12/12** |\n| **Spend: the same request while somebody holds it** | **refused 12/12** | no claim survives |\n| Withhold: a second agent asks about claimed work | refused **12/12** | refused **0/12** |\n| Guard: an edit to claimed work | refused **12/12** | refused **0/12** |\n| Action: a pull request touching a claimed topic | commented **12/12** | commented **0/12** |\n| Paid: a bought answer, found by the next agent | kept **12/12** | kept **0/12** |\n\nThe first two rows are the memory deciding whether money moves. With the store,\nthe second identical request costs nothing. Without it, the agent pays again\nevery single time. And while somebody holds the topic, it refuses to spend at\nall - a bought answer would be stale before it arrived, and the holder is the\ncheaper place to ask.\n\n12 trials, seed 1337, against the product's own refusal code -\n[`scripts/ablation.py`](https://github.com/drexthealpha/Knos/blob/main/scripts/ablation.py), written to\n[`docs/evidence/ablation.json`](https://github.com/drexthealpha/Knos/blob/main/docs/evidence/ablation.json) and pinned by\n[`tests/test_ablation.py`](https://github.com/drexthealpha/Knos/blob/main/tests/test_ablation.py).\n\n**Memory is not a feature here, it is the mechanism.** A claim has no second\ncopy. Delete the store and the refusal is not degraded, it is impossible.\n\n## Read this first\n\nThree MCP tools over stdio, one SQLite file, no server and no network. What\nmakes it different from a memory is that it **refuses**: ask about work\nanother agent claimed and there is no answer, only who has it. With\n`knos guard --install` the refusal reaches the edit itself.\n\n**Where the memory is read and written.** One file, `~/.knos//memory.db`,\nthrough [Sibyl](https://github.com/Sibyl-Labs/Sibyl-Memory). Every arrow below\nis a call site you can open, and\n[`tests/test_sibyl_is_load_bearing.py`](https://github.com/drexthealpha/Knos/blob/main/tests/test_sibyl_is_load_bearing.py)\ndeletes the file and asserts the product stops working.\n\n```mermaid\nflowchart LR\n CLAIM[\"knos claim\"] -->|\"claim_if_free\"| DB[(\"memory.db
one SQLite file\")]\n TELL[\"knos remember\"] -->|\"record, note_thing\"| DB\n READ[\"knos point
git log, CLAUDE.md, sessions\"] -->|\"note_thing\"| DB\n\n DB -->|\"search\"| ASK[\"MCP search / about
withheld if claimed\"]\n DB -->|\"claims\"| GUARD[\"guard.check
refuses the edit\"]\n DB -->|\"things, claims\"| EXP[\"knos export
.knos/decisions.md\"]\n DB -->|\"journal, only_here\"| ST[\"knos status\"]\n\n style DB fill:#1f2933,stroke:#7b8794,color:#ffffff\n style ASK fill:#fdf0e8,stroke:#a5744a,color:#111111\n style GUARD fill:#fdf0e8,stroke:#a5744a,color:#111111\n```\n\nWritten on the left, read on the right. Delete the box in the middle and\neverything on the right stops — that is the whole of what \"load-bearing\"\nmeans here, and it is a test rather than a sentence.\n\n| Tier | What lives there | Written by | Read by |\n|---|---|---|---|\n| HOT | the live claim, one row per topic, overwritten | `Memory.claim_if_free` | `mcp.search`, `guard.check` |\n| WARM | decisions, files, named things | `Memory.note_thing` | `answer.ask`, `knos export` |\n| COLD | the journal: what you told it, who stood down, every override | `Memory.record` | `knos status`, `knos notes` |\n\nSibyl's five tiers are used for what they are, not as one key-value bucket:\na claim is about *now* and is overwritten, a decision is a named thing\nreplaced in place, and history is only ever appended to.\n\n```mermaid\nflowchart TD\n subgraph DB[\"memory.db - hard cap 5 MB, Sibyl's free tier\"]\n HOT[\"HOT - the live claim
one row per topic, overwritten
lapses after 30 min\"]\n WARM[\"WARM - decisions, files, entities
named, replaced in place\"]\n COLD[\"COLD - the journal
append-only: told, stood down, overridden\"]\n end\n\n HOT -->|\"a second agent asks\"| NO[\"withheld
+ who holds it\"]\n WARM -->|\"knos ask\"| SRC[\"answer + file and line\"]\n COLD -->|\"knos status\"| ONLY[\"how many things exist nowhere else\"]\n DB -->|\"from 4 MB\"| FULL[\"nearly full
at 5 MB a claim is refused in words,
never dropped\"]\n\n style DB fill:#1f2933,stroke:#7b8794,color:#ffffff\n style HOT fill:#2b3a44,stroke:#7b8794,color:#ffffff\n style WARM fill:#2b3a44,stroke:#7b8794,color:#ffffff\n style COLD fill:#2b3a44,stroke:#7b8794,color:#ffffff\n style FULL fill:#f5f5f5,stroke:#999999,color:#111111\n```\n\n**Five things here that are not elsewhere.** Each one is a link, and each one\nis a command or a test rather than a claim:\n\n1. [A claim withholds the answer](#what-a-claim-does-here), instead of\n attaching a warning to it. Every other tool's claim is advisory.\n2. [The guard refuses the edit](#what-it-cannot-do) in Claude Code, Cursor\n and OpenCode — through their hooks, which are not MCP.\n3. [A hold is bound to the connection](https://github.com/drexthealpha/Knos/blob/main/docs/core-flow.md) that made it, so an\n agent naming itself the holder is still refused.\n4. [Every worktree is one memory](https://github.com/drexthealpha/Knos/blob/main/tests/test_worktrees.py), because the store\n is keyed on `git rev-parse --git-common-dir`. Tools that key on the\n worktree root fragment a repo's memory once per tree.\n5. [Delete the store and the product stops](https://github.com/drexthealpha/Knos/blob/main/tests/test_sibyl_is_load_bearing.py).\n Not degrades — stops.\n\n**The three stacks, and what each one actually does here.**\n\n| Stack | What it does in this repo | Where | Check it without installing anything |\n|---|---|---|---|\n| **Sibyl Memory** | the store. Every claim, answer, journal entry and export goes through it. Required. | `src/knos/memory.py` | [`tests/test_sibyl_is_load_bearing.py`](https://github.com/drexthealpha/Knos/blob/main/tests/test_sibyl_is_load_bearing.py) deletes it and watches the product fail |\n| **Base** | `knos share ./src --with alice.base.eth` records who may read what, onchain, so neither machine trusts the other's copy. Optional, testnet. | [`contracts/src/Access.sol`](https://github.com/drexthealpha/Knos/blob/main/contracts/src/Access.sol) | [contract `0x955fa320…6E52`](https://sepolia.basescan.org/address/0x955fa320D60D9172CF048141ed7eEE442da66E52), and [deploy](https://sepolia.basescan.org/tx/0xdcc25ff7460a09a080ec32016b39121b6a34b741f03411bcfdc2ee2a93b31d21) / [grant](https://sepolia.basescan.org/tx/0x84e11e21315b51e9e6b6453d226a44bcabf5a80f4c0085ba6f5b56ed169a92b6) / [revoke](https://sepolia.basescan.org/tx/0xb3ea6920c0a7bf7fa9dde64e6f0c2275e149f976bf20c909098a2431417adfb4) |\n| **Virtuals** | a **Telegram bot** that is also a registered ACP provider: it sells one answer out of this store, and pays over x402 for a brief it writes back with `knos remember`. Runs on the console with no Telegram account. Optional, off by default. | [`agent/bot.ts`](https://github.com/drexthealpha/Knos/blob/main/agent/bot.ts), [`agent/offering.ts`](https://github.com/drexthealpha/Knos/blob/main/agent/offering.ts), [`src/knos/buy402.py`](https://github.com/drexthealpha/Knos/blob/main/src/knos/buy402.py) | [the agent page](https://app.virtuals.io/acp/agents/01a05b97-a776-760a-9165-e9893e4091dc), and job 75659 in two legs: [escrow funded](https://basescan.org/tx/0x756b867b2b1165bfe674025a82d21cd765378a40ab226274bd555abf0065bd64), [provider paid](https://basescan.org/tx/0x95a84c44802d09e38ef920524f947dff0eb5a2fe972054fca97bfd989cbcea59) |\n\nBase and Virtuals are **optional and off by default** — Knos runs with both\nswitched off, and nothing on the read or answer path touches a network\n([`tests/test_no_network.py`](https://github.com/drexthealpha/Knos/blob/main/tests/test_no_network.py)). Every job traded\nthrough the Virtuals provider was bought by a test agent of mine, not by a\ncustomer. Details, including what each one does *not* do:\n[The two onchain parts](#the-two-onchain-parts-and-exactly-what-they-are).\n\n```mermaid\nflowchart TD\n DB[(\"memory.db
Sibyl - required\")]\n\n SHARE[\"knos share ./src --with alice\"] -->|\"who may read what\"| BASE[\"Base Sepolia
Access.sol\"]\n BASE -->|\"may_read\"| DB\n\n BUY[\"/brief BTC\"] -->|\"0.01 USDC over x402
Base mainnet\"| SELLER[\"a paid endpoint\"]\n SELLER -->|\"knos remember - the receipt
exists nowhere else\"| DB\n\n DB -->|\"knos ask\"| SELL[\"Virtuals ACP offering
sells one answer\"]\n\n OFF[\"both switched off - the default\"] -.->|\"knos still works\"| DB\n\n style DB fill:#1f2933,stroke:#7b8794,color:#ffffff\n style OFF fill:#f5f5f5,stroke:#999999,color:#111111,stroke-dasharray: 4 3\n```\n\nEvery one of those arrows ends at the same SQLite file. That is the point of\nincluding them at all: the commerce leg is not a second system beside the\nmemory, it reads and writes the one store, and\n`pytest tests/test_sibyl_is_load_bearing.py` takes the file away and asserts\nnone of it works.\n\n### The whole loop, in under a minute\n\nThis is the server path, for when you already run several agents yourself.\nThe repo-side loop needs none of it — the Action reads a committed file and\nnothing here has to be installed for that to work.\n\n```bash\npip install knos && knos connect # once, per machine, only if you want the server\nknos claim \"the parser\" # agent A takes it\n# ask any other agent about the parser — it is refused, and told who has it\nknos done # give it back\nknos export # writes .knos/decisions.md, commit it\n```\n\nClaim, be refused, release, export. The Action then does the same thing on a\npull request, for the people who never installed anything — which is most of\nthem, and is the point.\n\nAll of it runs without an editor open, as two real processes against one\nstore: `pytest tests/test_intent.py -k two_processes`. The other half of the\nproof is [`tests/test_sibyl_is_load_bearing.py`](https://github.com/drexthealpha/Knos/blob/main/tests/test_sibyl_is_load_bearing.py),\nwhich takes the store away and asserts that both the withholding and the\nanswers die with it.\n\nUnder it is a local MCP server: three tools over stdio — `search`, `about`,\n`remember`. No HTTP server, no ports, no account, no model download, no repo\nto register, and [no network connection at all](https://github.com/drexthealpha/Knos/blob/main/tests/test_no_network.py):\nthat last one is a test, not a promise.\n\n`knos connect` adds Knos to **Claude Code**, **Claude Desktop**, **Cursor**\nand **OpenCode** — whichever you have, each in the shape it reads\n(`mcpServers` for the first three, `mcp` with `\"type\": \"local\"` for\nOpenCode). For Claude Code it runs `claude mcp add --scope user`, which\nregisters the server with the session you are already in, so **its tools work\nimmediately with nothing to restart**.\n\nFor the other three, `knos connect` writes the config, takes a backup, and\nprints the one thing left to do: **quit the app and start it again**.\nNothing in the MCP spec lets a server register itself with a session that\nis already running. The exact keystroke per client, the Claude Desktop\nextension, the Claude Code plugin and the by-hand JSON are all in\n[docs/connect.md](https://github.com/drexthealpha/Knos/blob/main/docs/connect.md).\n\n\nThe first thing an agent asks about a repo reads it. Seven cold runs each,\nwhole process, Windows on a spinning disk (WSL on the same box: 3.4s median on a small repo): **1.7s median on a small project (1.5-2.1),\n2.0s on goose (1.8-3.4), 3.1s on the Linux kernel (3.0-6.8)** — 93,703 tracked\nfiles. What it does in that time is one `git log`, your `CLAUDE.md`, and the\ntranscripts of past sessions in that tree, written to SQLite. It happens once. Every question after it is\nunder 0.2s, and every agent you have shares the result.\n## What a claim does here\n\nClaude Code is rewriting the risk guard. You ask Cursor about it.\n\nEvery tool in the table below answers, and Cursor gives you a confident plan\nbuilt on the version that was on disk five minutes ago. Knos does this\ninstead:\n\n```\nWithheld. risk guard (held by Claude Code) is being worked on right now,\nso knos is not the place you find out about it. Ask them, or work on\nsomething else.\n```\n\nNot a warning attached to the answer — **no answer**. Your agent can still\ntake it, by saying why, and the reason is written down under its name where\nyou will read it. `knos done` releases it, and so does half an hour.\n\n`knos guard --install` takes that one step earlier: the same claim, consulted\nwhen an agent reaches for the file rather than when it asks a question, so the\nedit itself is refused. Claude Code, Cursor and OpenCode all run a hook before\na tool call and a hook can say no. It is off until you ask for it, and\n`knos guard --uninstall` takes it back out — details in\n[What it cannot do](#what-it-cannot-do).\n\n**What a claim covers.** A claim and a question are treated as the same\nsubject when they share a word stem, and identifiers are split into their\nparts first, so a claim on `the risk guard` covers `risk_guard.py`. The\nclaim is matched against the passages the question would have returned as\nwell as against the question itself, so rewording the question does not get\npast it — asking *why do we cap trades?* while `the risk guard` is claimed\nis withheld like the plain question. This is word matching, not meaning: a\nquestion that shares no stem with the claim *and* returns no passage that\ndoes will still be answered. Check it:\n`pytest tests/test_intent.py -k \"paraphrased or reaches_the_file\"`.\n\n`search` withholds. `about` is a named lookup and does not: it answers, with\nthe holder's name and how long ago they started shown above the answer.\n\nEvery cell below comes from that tool's own README or documentation page, so\nyou can check each one:\n\n| | To install | MCP tools | Needs | Refuses to answer about work another agent claimed |\n|---|---|---|---|---|\n| `CLAUDE.md` + worktrees | — | — | nothing | no |\n| [agentmemory](https://github.com/rohitg00/agentmemory) | `npx -y @agentmemory/agentmemory@latest` | **54** (8 in core mode) | a server on ports 3111/3112/3113/49134 | no — `memory_lease` locks an *action* an agent chooses to take |\n| [mcp-local-memory](https://github.com/Beledarian/mcp-local-memory) | npx entry in your config | 18 | may download an embedding model | no |\n| [Engram](https://github.com/Gentleman-Programming/engram) | `brew install` + `engram setup ` | 16 | nothing — one binary | not addressed |\n| [MemPalace](https://github.com/MemPalace/mempalace) | `uv tool install mempalace` + `init` + `mine` | 45 | ~300 MB embedding model | no — separate wings per agent |\n| [Hindsight](https://github.com/vectorize-io/hindsight) | `docker run …` or pip | 3 per bank | Postgres + pgvector + an LLM API key | no — banks are isolated by design |\n| [Vibsync](https://vibsync.com/agent-coordination) | remote MCP URL + an account | claim/release, check_conflicts, remember/recall, task board | a hosted server | no — its own page: \"cooperative, not enforced — a rogue agent can still ignore it\" |\n| [CoordMCP](https://glama.ai/mcp/servers/siddiquesahabaj/CoordMCP) | `pip install coordmcp` | **52** | a coordination server running | no — `lock_files` blocks edits, not reads |\n| [Memryzed](https://github.com/memryzed/memryzed) | `curl -fsSL https://memryzed.com/install.sh \\| bash` | 9 | nothing — one SQLite file | not addressed |\n| [Agent Claim MCP](https://glama.ai/mcp/servers/vk0dev/agent-claim-mcp) | npx entry in your config | 3 | nothing | no — and it is not a memory system: claims only, no sessions or decisions |\n| [Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail_rust) | `curl … install.sh \\| bash` | **45** (plus 25 resources) | a listener on 127.0.0.1:8765 | no — reservations are advisory; its git hook blocks a *commit*, and the memory stays fully readable |\n| **Knos** | **a workflow file, or `from knos.core import Claims`; the server is optional** | **3** | **nothing** | **yes** |\n\nKnos is not the only tool with claims, and that column would be dishonest if\nit implied so. Vibsync, CoordMCP, AgentRoom and Agent Claim MCP all let an\nagent claim something; agentmemory has leases. The difference is what a claim\n*does*. Everywhere else it is a signal about a file, which an agent may check\nbefore editing and may ignore — Vibsync says so itself, and CoordMCP's locks\nstop edits while the memory stays fully readable. Knos changes what the memory\nsays: ask about work someone else claimed and there is no answer to act on,\nand the claim is bound to the connection that made it, so an agent naming\nitself the holder is still refused.\n\nThree of these are worth your attention for reasons other than that column.\nMemryzed is local, keyless and one SQLite file — the same shape as Knos, with\nmore recall tools and no coordination. Vibsync is the only one that shares a\nclaim across machines, which Knos does not: a committed `.knos/decisions.md`\nis as far as a claim travels here. **Agent Mail is the closest thing to a\ncompetitor on enforcement, and on one axis it goes further than Knos**: its\npre-commit git hook refuses a commit that touches files another agent has\nreserved. Knos refuses the *answer*; Agent Mail refuses the *commit*, by which\npoint the work is already done. Neither of them stops the keystroke. Both are\nworth knowing about, and Agent Mail costs a listener on port 8765 and 45 tools\nwhere this costs neither.\n\nKnos is not trying to out-remember these tools. It is trying to be the one\nthat speaks up while two agents are in the same code, and to cost you two\ncommands and three tools to find out.\n\n## One agent is enough to see it\n\n```bash\nknos claim \"the parser\"\n```\n\nAsk your agent about the parser. It is refused, and tells you so. `knos done`\nand it answers again. That is the whole mechanism, in two commands.\n\n```mermaid\nflowchart TD\n P[\"pip install knos
knos connect\"] --> CC[\"Claude Code\"]\n P --> CU[\"Cursor\"]\n P --> CD[\"Claude Desktop\"]\n P --> OC[\"OpenCode\"]\n\n CC -->|\"first question reads the repo\"| S[(\"one SQLite file
no server, no model\")]\n CU --> S\n CD --> S\n OC --> S\n\n R[\"CLAUDE.md, AGENTS.md, ADRs
commits, past sessions\"] --> S\n W[\"every worktree of this repo\"] --> S\n\n S -->|\"answers, with the source\"| CC\n S -->|\"withheld - Claude Code is on it\"| CU\n\n style S fill:#1f2933,stroke:#7b8794,color:#ffffff\n style P fill:#e8f0fe,stroke:#4a6fa5,color:#111111\n style R fill:#f5f5f5,stroke:#999999,color:#111111\n style W fill:#f5f5f5,stroke:#999999,color:#111111\n```\n\nEvery arrow above is a command you can run: the withheld one is\n`knos claim \"the parser\"` then asking a second agent, and\n`pytest tests/test_intent.py -k withholds_the_answer` is the same thing as a\ntest.\n\n## What breaks without the store\n\nEvery capability below reads or writes the one SQLite file. The middle column\nis the command that exercises it; the right column is where it touches the\nstore. `pytest tests/test_sibyl_is_load_bearing.py` takes the file away and\nasserts the first three rows stop working.\n\n| Capability | Run it | Where it touches the store |\n|---|---|---|\n| A claim is taken, once, atomically | `knos claim \"the parser\"` | `Memory.claim_if_free` — compare-and-swap into HOT state, `src/knos/memory.py` |\n| A second agent is refused | ask any other agent about it | `mcp.search` → `_being_worked_on` reads HOT, `src/knos/mcp.py` |\n| Who stood down, and who overrode | `knos status` | COLD journal via `Memory.stood_down` / `_took_it_anyway` |\n| What you told it | `knos remember \"...\"` | `Memory.record` → journal, `Memory.note_thing` → WARM entity |\n| Decisions shared with the repo | `knos export` | WARM + HOT read out into `.knos/decisions.md` |\n| A brief bought over x402 | `/brief BTC` in the bot | `knos remember` after payment — the receipt exists nowhere else |\n| An ACP deliverable | a buyer funds a job | `agent/offering.ts` shells to `knos ask`, which reads the store |\n| How full it is, and what dies | `knos status` | `Memory.size_mb`, `Memory.only_here` |\n\nThe claim lives in HOT because it is about *now* and is overwritten, not\nappended. Decisions live in WARM because they are named things replaced in\nplace. History lives in COLD because it is append-only. That is Sibyl's\nschema used as intended rather than as a key-value bucket, and `knos status`\nprints the tiers by name.\n\n## How memory made this possible\n\nKnos is not a tool that happens to save things. Take Sibyl out and there is\nno product left to run.\n\nThe claim lives in the store. That is the whole mechanism: one agent writes\nthat it is changing something, and another agent whose question or whose\nanswer touches that subject is handed the holder's name instead. Delete the file and there is\nnothing to read, so nothing is withheld, so two agents edit the same thing\nand neither is told. The refusal is not a rule enforced in code somewhere\nelse — it *is* a read of the store, and it fails when the read fails.\n\nThe same file is the only copy of three other things. What you told it with\n`knos remember`. The brief the agent paid for over x402, which was bought\nonce and exists nowhere else on the machine. The ACP job it sold, and what it\nsold. Your commits and your `CLAUDE.md` come back after a delete, because\nthose are your files; none of these do.\n\n`knos status` prints that number directly — how many things exist nowhere\nelse. The table in [What breaks without the\nstore](#what-breaks-without-the-store) names the call site for each one, and\n[`tests/test_sibyl_is_load_bearing.py`](https://github.com/drexthealpha/Knos/blob/main/tests/test_sibyl_is_load_bearing.py)\nruns the test a sceptic would run first: remove the memory, watch the\nproduct fail.\n\n## Share it with the repo, not a server\n\nEverything above is local. Two things, though, exist nowhere a teammate can\nreach — what somebody decided, and what somebody is working on right now. So\nthose go in the repository, as a file you commit:\n\n```bash\nknos export # writes .knos/decisions.md\ngit add .knos && git commit -m \"share decisions\"\n```\n\nIf your repo already keeps decisions somewhere, write there instead:\n\n```bash\nknos export --to docs/decisions/0001-knos.md\n```\n\nKnos reads `.knos/decisions.md`, `DECISIONS.md`, `WORKLOG.md` and\n`docs/adr/*.md` back on the next question, so any of those close the loop\nwith no configuration. Anywhere else is still written and still worth\ncommitting, and `knos export` tells you it will not be read back rather than\nletting you find out later.\n\nThat one file is the whole mechanism. It is markdown, it diffs in review, and\nthree different kinds of reader consume it without installing anything:\n\n- **A teammate clones and asks.** `.knos/decisions.md` is one of the decision\n records Knos already reads, so a clean clone answers from it on its first\n question — no install, no sync, no account, no server between the two\n machines (`pytest tests/test_shared_repo.py -k second_clean_clone`).\n- **Every agent on their machine reads it too**, through the same three MCP\n tools, on the same first question. A contributor who has never heard of\n Knos still gets your decisions, because their agent asks and the file is\n already in the checkout.\n- **CI reads it on a pull request** and says so when the branch touches work\n somebody has claimed (`pytest tests/test_shared_repo.py -k ci_warns`).\n\nThe comment is a heads-up, never a failure — `action/knos_pr_check.py`\nexits 0 on every path, including when it finds a conflict and when it\ncrashes. The workflow is eight lines:\n[The pull request check](#the-pull-request-check).\n\n**It runs both ways, and that is the part that compounds.** The teammate who\ncloned runs `knos export` too. Their decisions and their claims land in the\nsame file, you pull, and your agents read what they decided while you were\nnot looking. Every contributor writes to the file and reads from it, so it\nholds more after each one than before. The repository is the shared object:\nthere is no database of ours, no protocol to adopt, and no server to pay\nfor.\n\nSecrets do not travel: a note about `.env` is filtered out of the exported\nfile by the same check that hides `.env` from an agent\n(`pytest tests/test_shared_repo.py -k private_note`).\n\n**Nothing outside this repository has adopted it yet.** The loop is\nimplemented and tested, six tests in `tests/test_shared_repo.py`. That is a\nmechanism that works, not a network that exists.\n\n\n## The pull request check, in detail\n\nThe workflow is [at the top](#start-here-the-action); this is what it does\nonce it is there.\n\n`.knos/decisions.md` is the whole interface. A maintainer writes it by hand or\ngenerates it with `knos export`, commits it, and the Action reads that file\nand nothing else from your side. Claims lapse after 30 minutes, so a stale\nfile simply stops matching rather than warning about work that finished\nyesterday.\n\n**The order of adoption that costs least.** Add the Action. Commit a\n`.knos/decisions.md` with the two or three things currently in flight. That is\nthe whole first run, and it works whether or not anybody on the repo uses an\nagent. Agents that want to read and write the same file can connect later, or\nnever.\n\n**The three folders, so nothing here is a surprise.** `src/knos/` is the\nproduct: the claim, the withhold, `knos export`, and\n[`core.py`](https://github.com/drexthealpha/Knos/blob/main/src/knos/core.py), the importable version of the claim for tools\nthat would rather embed it than run a server. `action/` is\nthe pull request check above. `agent/` is a Telegram bot that is also a\nregistered Virtuals agent — it pays for things over x402 on Base and sells\nanswers as ACP jobs, and every one of those paths reads and writes the same\nstore. It is the commerce leg, not the product; Knos works with it switched\noff, which is the default. `contracts/` is one Solidity file behind\n`knos share`. Details in [The two onchain parts](#the-two-onchain-parts-and-exactly-what-they-are).\n\n`pull_request_target` works too, if you want the check on pull requests from\nforks: the Action reads only the committed `.knos/decisions.md` and the pull\nrequest's own title, body and file list, and never checks out or runs\nanything from the head branch.\n## Who this is for, and the pain they have written down\n\n**The audience is maintainers and contributors on repositories where more\nthan one coding agent touches the same tree** — a person running Claude Code\nin the terminal and Cursor in the editor, a team whose contributors point\nagents at the same issue, or a repository that accepts agent-written pull\nrequests. They share one failure: two agents change the same thing, neither\nis told, and it surfaces at merge.\n\nNothing below is about Knos. These are their own open issues, in their own\nrepositories, filed by people who have never heard of it. Every one was open\nwhen this was written; each link resolves in a click.\n\n| Repository | Stars | The issue |\n|---|---|---|\n| openai/codex | 121k | [Add a cross-agent intent map to prevent overlapping edits](https://github.com/openai/codex/issues/36719) |\n| openai/codex | 121k | [Automatically isolate and coordinate concurrent writes across chats and agents](https://github.com/openai/codex/issues/37226) |\n| anthropics/claude-code | 144k | [Subagent exceeded scope and executed an unauthorized git commit](https://github.com/anthropics/claude-code/issues/91872) |\n| openclaw/openclaw | 389k | [Errors flood the logs under explicit multi-agent ownership](https://github.com/openclaw/openclaw/issues/126360) |\n| CopilotKit/CopilotKit | 37k | [Agents mutate a shared singleton per-request; concurrent users leak system prompts](https://github.com/CopilotKit/CopilotKit/issues/5659) |\n| omnigent-ai/omnigent | 9.7k | [Session-state writes race under concurrent updates: lost updates and orphan rows](https://github.com/omnigent-ai/omnigent/issues/3402) |\n| microsoft/winappCli | 1.2k | [Cooperative UI turns for concurrent UI agents](https://github.com/microsoft/winappCli/issues/764) |\n| microsoft/winappCli | 1.2k | [Add worktree-isolated identity to `winapp run`](https://github.com/microsoft/winappCli/issues/763) |\n\nThe first two are the sharpest: `openai/codex` has an open request for a\nrecord of what each agent intends to edit, so that two of them do not edit\nthe same thing. That is the mechanism in [What a claim does\nhere](#what-a-claim-does-here), asked for by somebody else, in a repository\nwith 121,000 stars.\n\n### One repository coordinating agents through a GitHub issue, today\n\n`tsz-org/tsz` runs its agents against a claim board:\n[issue #17314](https://github.com/tsz-org/tsz/issues/17314), open, with 1,133\ncomments. It succeeded [#15994](https://github.com/tsz-org/tsz/issues/15994),\nwhich was forked after hitting the 2,500-comment cap. Agents post `CLAIM`,\n`DONE`, `DROP` and `BLOCK` lines and are expected to read the thread before\nstarting, and its standing notes record what goes wrong: sessions that end on\na live claim with no closing record, and two claims naming one defect in\ndifferent words.\n\nThat is this product's job, done by hand in a comment thread, at a size where\nreading it before every edit has stopped being possible.\n\n**What this is and is not.** It is evidence that the problem is real and that\npeople with large audiences have written it down. It is not evidence that\nanybody uses Knos. **No repository outside this one has adopted it.** The\nloop is implemented and tested — six tests in `tests/test_shared_repo.py` —\nwhich makes it a mechanism that works, not a network that exists.\n\n## Check any of it in under a minute\n\nNothing here is a claim. Each row is a command; run it and see. The\ncommands are checked by a test, so a renamed test fails the suite rather\nthan leaving a dead instruction here\n(`pytest tests/test_cli.py -k every_check_command`).\n\n| What | How to check it yourself |\n|---|---|\n| A claim changes what other agents are told | `knos claim \"the parser\"` — it prints the exact refusal your agents now get. `knos done` gives it back. |\n| One agent's claim reaches another agent's **live** session, with no restart or cache | `pytest tests/test_no_network.py -k live_session` — one process claims, a second sees it on its next call |\n| No network connection, ever | `pytest tests/test_no_network.py` — breaks `socket.connect`, `bind`, `create_connection`, `getaddrinfo`, then reads a repo, answers, writes, claims, withholds, overrides. A third test breaks the guard on purpose, so it cannot pass by doing nothing |\n| Decisions you keep in the repo are read | `pytest tests/test_rules.py -k decisions_kept_beside` — an ADR answers with `docs/adr/0001-use-sqlite.md:3` |\n| Every worktree of a repo is one memory | `pytest tests/test_worktrees.py` |\n| A big repo is never half-read | `pytest tests/test_worktrees.py -k runs_out_of_time` — both readers, forced to time out, leave nothing behind |\n| Secrets are invisible, not redacted | `pytest tests/test_private.py` — the search layer is asked directly, with an agent's identity |\n| Three MCP tools, no more | `pytest tests/test_recall.py -k three_tools_are_listed` |\n| Two agents cannot both hold the same claim | `pytest tests/test_intent.py -k two_processes` — two real processes race for one topic; one wins, the other is told who has it |\n| A crashed agent cannot hold work forever | `pytest tests/test_intent.py -k lapses` |\n| A reworded question is withheld too | `pytest tests/test_intent.py -k paraphrased` — `the risk guard` is claimed, the question shares no word with it, the answer is still refused |\n| A claim reaches the file it names | `pytest tests/test_intent.py -k reaches_the_file` — `the risk guard` covers `risk_guard.py`, and still does not cover `safeguarding` |\n| Every command has a `knos help` page | `pytest tests/test_cli.py -k has_a_help_page` |\n| The pull request check can never fail a build | `pytest tests/test_shared_repo.py -k never_returns_non_zero` |\n| CI comments on decisions, not only claims | `pytest tests/test_shared_repo.py -k reports_decisions` |\n| A full store refuses a claim rather than dropping it | `pytest tests/test_sibyl_is_load_bearing.py -k full_store` |\n| `knos status` says how many claims are held | `pytest tests/test_sibyl_is_load_bearing.py -k counts_the_claims` |\n| `knos connect` names the exact restart per client | `pytest tests/test_cli.py -k exact_restart` |\n\nCost, if you take the Action: a workflow file, and nothing installed\nanywhere. Cost, if you embed the core: one import. Cost, if you run the\nserver: `pip install knos`. No account, no key, no model download, no network\nrequest on any of those paths, and a 5 MB free-tier cap per repo.\n\n## Everything else, briefly\n\nEvery answer names where it came from — a commit, a session and a date, or a\nfile and a line. Knos has no model: it does not summarise and it does not\nguess, it finds what somebody actually said.\n\n```\n$ knos ask \"what are the rules here?\"\n\nAsk before adding a dependency. The build is the product.\n AGENTS.md:3\nEvery change ships with a test. A green run you did not watch is not green.\n CLAUDE.md:8\n```\n\n| Source | From |\n|---|---|\n| Your rules | `CLAUDE.md`, `AGENTS.md` |\n| Decisions in the repo | `.knos/decisions.md`, `DECISIONS.md`, `WORKLOG.md`, `docs/adr/*.md`, `docs/decisions/*.md` |\n| Agent sessions | Claude Code transcripts, Cursor's history |\n| Commits | `git log` |\n| Code structure | read by Knos itself, or [universal-ctags](https://github.com/universal-ctags/ctags) when you have it |\n| What you tell it | `knos remember` |\n\n### What is covered, and what is not\n\nKnos is wired into **4 clients** and reads the past session history of **2**.\nBoth numbers are the honest ones:\n\n| Client | MCP tools | Reads its past sessions |\n|---|---|---|\n| Claude Code | yes, no restart | yes |\n| Cursor | yes | yes |\n| Claude Desktop | yes | no |\n| OpenCode | yes | no |\n| Hermes Agent | via [knos-hermes](https://github.com/drexthealpha/knos-hermes) | no |\n| Gemini CLI, Codex, Windsurf, Aider, Continue | no | no |\n\nWiring a client is three edits and a test — [CONTRIBUTING.md](https://github.com/drexthealpha/Knos/blob/main/CONTRIBUTING.md)\nhas them, with OpenCode as the worked example. A session reader is about 40\nlines: **Codex CLI and Gemini CLI are the two missing ones**, each a small\nparser plus one test, written up in\n[`.github/GOOD_FIRST_ISSUES.md`](https://github.com/drexthealpha/Knos/blob/main/.github/GOOD_FIRST_ISSUES.md).\n\n**Knos does not have memory of every local workflow, and does not claim to.**\n\n`.env`, `*.pem`, `id_rsa`, `.ssh`, `.aws` and twelve more are private the\nmoment Knos reads a repo, without being asked. Private means invisible, not\nredacted: an agent asking about one is told nothing at all — no result, no\ncount, no \"2 hidden\".\n\n**Worktrees.** Keep them; they do a different job, and Knos treats every\nworktree of a repo as one memory anyway. Read the repo in one tree and every\nother tree can answer. Claim in one and the agents in the others are held off.\n\nThe whole mechanism is one git command. `git rev-parse --show-toplevel`\nreturns the worktree root, so every worktree looks like a different project;\n`git rev-parse --git-common-dir` returns the git directory the worktrees\nshare, which is identical across all of them. Knos keys the store on the\nsecond. Tools that key on the first fragment a repo's memory once per\nworktree — [that bug, in another\ntool](https://github.com/rohitg00/agentmemory/issues/515). Check it:\n`pytest tests/test_worktrees.py`.\n\n**A claim lapses after 30 minutes.** An agent that crashes mid-change\nnever calls `knos done`. If the claim outlived the process, that work would\nbe unaskable until a person noticed and cleared it by hand. Instead the hold\nexpires on its own, and the next agent to ask gets a real answer. Taking a\nclaim is a compare-and-swap, not a blind write, so two agents reaching for\nthe same work in the same second do not both believe they have it: one wins,\nthe other is told who holds it. Check both:\n`pytest tests/test_intent.py -k \"lapses or two_processes\"`.\n\n**Five tiers, one file, a hard 5 MB cap.** Sibyl's schema is not a black box\nKnos writes blobs into — it uses the tiers for what they are. Live claims go\nin HOT, one row per topic, overwritten rather than appended. Decisions and\nfiles go in WARM. History goes in COLD, append-only. The whole thing is\ncapped at 5 MB by Sibyl's free tier, and `knos status` prints the size and\nsays `nearly full` from 4 MB, so a store that is filling up tells you before\nit stops taking writes rather than after\n(`pytest tests/test_sibyl_is_load_bearing.py -k cap_and_warns`). At 5 MB a\nclaim is **refused in words, not dropped**: an agent that thinks it holds\nwork it does not is the exact failure this whole feature exists to prevent\n(`pytest tests/test_sibyl_is_load_bearing.py -k full_store`).\n\n**Commands.** `knos ask`, `knos claim`, `knos done`, `knos status`,\n`knos export`. `knos help` lists the rest. Nothing runs itself: no watcher,\nno daemon, no schedule.\n\n### Speed, on the one question this is for\n\n\"What was decided, and is anyone on it?\" — warm, whole process, median of 7:\n\n| | Knos | `git log --all -S` |\n|---|---|---|\n| small repo | 960ms | **33ms** |\n| Linux kernel (93,703 files) | **920ms** | 28,289ms |\n\nGit wins on a small repo and it is not close. Knos's time is flat with repo\nsize because it reads an index rather than walking history; git's grows with\nit. On the kernel that is 30x, and most of Knos's 900ms is Python starting up.\n\n**Knos is not faster than git at anything git is for**, and a cold first read\nof a large repo is slower than either — 3.1s median, stated above.\n\n**What agents actually read.** A study of 557 agent sessions and\n33,097 pull requests measured that **60.5%** of everything coding agents do\nwith documentation happens in instruction files and their own notes —\n`CLAUDE.md`, `AGENTS.md`, plans, scratch notes — against 10.6% for classical\ndocs and 1.3% for API references\n([Gao & Chen, 2026](https://arxiv.org/abs/2608.20195)).\n\nThat is a measurement of where agents spend their documentation time, and it\nis the whole of what the paper is cited for here. The paper itself states that\nthe link between what agents consult and what they edit is unresolved. It does\nnot study Knos, does not say a tool like Knos is needed, and is not evidence\nthat anyone will adopt one.\n\nKnos is one practical response to that measured behaviour: it reads those same\ninstruction files as a source and answers from them with a file and a line.\nTwo other things are true on their own account, and the paper is not the reason\nto believe either — a file cannot say who is reading it, and it cannot say what\nanother agent is changing right now.\n\n## What happens when you delete the memory\n\nOne SQLite file at `~/.knos//memory.db`, via\n[Sibyl](https://github.com/Sibyl-Labs/Sibyl-Memory), **capped at 5 MB per\nrepo** — Sibyl's free tier, and Knos runs it unactivated, so there is no\naccount to make and no cap to raise. Sessions and commits are read newest\nfirst, so when a repo fills, what you have is the recent end of both and the\nolder end was never read. Nothing already stored is evicted or truncated, and\n`knos status` says `nearly full` from 4 MB. The Linux kernel filled 0.3 MB.\n\nNothing leaves this machine — Knos makes no network request. Delete that\nfile and:\n\n| | Gone forever | Why |\n|---|---|---|\n| What you told it (`remember`) | **yes** | it existed nowhere else |\n| Every claim, and the withholding | **yes** | same |\n| Who stood down for whom, every override | **yes** | same |\n| Your commits, `CLAUDE.md`, past sessions | no — re-read | they are your files, not Knos's |\n\n`knos status` counts that first row for you, so you never take it on trust:\n\n```\njournal 330 things learned\n 0 of them exist nowhere else - told, claimed, stood down\n delete the store and only those go; the rest is re-read from your repo\n```\n\nTen seconds to prove it: claim something, watch an agent be refused, delete\nthe file, ask again. Nothing was ever held.\n\nMore on the five tiers, why a claim expires, and how a hold is bound to a\nconnection so an agent cannot borrow somebody else's name:\n[docs/core-flow.md](https://github.com/drexthealpha/Knos/blob/main/docs/core-flow.md).\n\n## The two onchain parts, and exactly what they are\n\nBoth are optional. Knos works with neither, and nothing on the read or answer\npath touches a network — that is what `pytest tests/test_no_network.py`\nchecks.\n\n### Base: sharing one folder with a teammate\n\n```bash\nknos share ./src --with alice.base.eth\nknos unshare ./src --with alice.base.eth\n```\n\n**What it does.** Their agent can read that folder and nothing else. The\nrecord of who may read what is [Access.sol](https://github.com/drexthealpha/Knos/blob/main/contracts/src/Access.sol) on Base\nSepolia, so neither machine has to trust the other's copy of the answer.\nTestnet, so it costs nothing.\n\n**What it does not do.** It does not move your memory anywhere — the store\nstays on your disk. It does not encrypt anything. It is one permission bit\nper person per folder, not a sync protocol.\n\n**How to verify it.** Two commands and one number each way:\n\n```bash\npython -c \"from knos import team; o=team.identity('owner').address; m=team.identity('teammate').address; \\\nteam.share('crates','teammate'); print(team.may_read(o,'crates',m)); \\\nteam.unshare('crates','teammate'); print(team.may_read(o,'crates',m))\"\n# True\n# False\n```\n\nOr read it without running anything: contract\n[`0x955fa320…6E52`](https://sepolia.basescan.org/address/0x955fa320D60D9172CF048141ed7eEE442da66E52),\nand one full cycle —\n[deploy](https://sepolia.basescan.org/tx/0xdcc25ff7460a09a080ec32016b39121b6a34b741f03411bcfdc2ee2a93b31d21),\n[grant](https://sepolia.basescan.org/tx/0x84e11e21315b51e9e6b6453d226a44bcabf5a80f4c0085ba6f5b56ed169a92b6),\n[revoke](https://sepolia.basescan.org/tx/0xb3ea6920c0a7bf7fa9dde64e6f0c2275e149f976bf20c909098a2431417adfb4).\nNine contract tests: `cd contracts && forge test`.\n\n### Virtuals: selling one answer\n\n**What it does.** Knos is registered on the Virtuals marketplace as a\nprovider with one offering: another agent pays 0.01 USDC for an answer out of\nthis machine's memory. The seller is [agent/offering.ts](https://github.com/drexthealpha/Knos/blob/main/agent/offering.ts).\n\n[agent/bot.ts](https://github.com/drexthealpha/Knos/blob/main/agent/bot.ts) is that same agent with a chat face, in one\nprocess: it answers ACP jobs, it answers `/ask` out of the same store, and\n`/brief` buys something over x402 on Base and writes what it bought back with\n`knos remember`, so the next agent on the machine gets it without paying.\nEvery one of those paths reads or writes the same SQLite file —\n`pytest tests/test_sibyl_is_load_bearing.py` takes it away and asserts none\nof them work.\n\nStarted with no Telegram token it reads commands from the console, so the\nwhole thing runs without an account. This is the same handler Telegram calls,\nwired to stdout, so what a person sees in the chat is what prints here:\n\n```\n$ npm --prefix agent run bot -- /status\nKnos - one memory every coding agent here shares.\n\nNothing is claimed, so nothing is being withheld.\n\n10 things written down that exist nowhere else\n0.5 MB of 5 MB used\nShared by: Claude Code, Cursor\n\nDelete the store and only those 10 go. Everything else is re-read from the repo.\n```\n\n`` markers around the bold words are left out above; Telegram renders them\nand a terminal prints them literally. `/help` lists the five commands, and an\nunrecognised one is answered rather than ignored - `tests/test_bot.py`.\n\n**The x402 half is live on Base mainnet.** `/brief BTC` pays 0.01 USDC to\n[x402-seller](https://x402-seller-m8nx.onrender.com)'s market-regime endpoint\nand writes what it bought into the store with its receipt. Five settled so\nfar, signed by `0xEca35a0C…48C1`:\n[`0x2ce6af5c…`](https://basescan.org/tx/0x2ce6af5c1c223a5b1395cbae719a96d7f1ded74fd90f909375142f9e4a14d9ca),\n[`0x20983f7b…`](https://basescan.org/tx/0x20983f7ba5afc2cc96da402e1509e8f267c15e4068048f6397bee4bb13537d04).\nThe client is [src/knos/buy402.py](https://github.com/drexthealpha/Knos/blob/main/src/knos/buy402.py), which signs with the\nkeystore knos made itself — there is no private key in any config file.\n\nTwo routes on that seller, `/markets` and `/signal`, return 502 after the\n402. They cost nothing (the payment never settles) but they are why `/brief`\nis the only route wired in.\n\n**What it does not do.** There is no evaluator and no reputation system, and\n**every job traded through it was bought by a test agent of mine, not by a\ncustomer.** It is off by default and runs only when you start it.\n\n**How to verify it.** The agent page is public — open\n[app.virtuals.io/acp/agents/01a05b97…](https://app.virtuals.io/acp/agents/01a05b97-a776-760a-9165-e9893e4091dc)\nand you will see the registration without installing anything. Job 75659 is\non Base mainnet, in two legs, neither of which needs an account to read:\n[buyer pays 0.01 USDC into escrow](https://basescan.org/tx/0x756b867b2b1165bfe674025a82d21cd765378a40ab226274bd555abf0065bd64),\nthen [escrow releases 0.0095 to the provider](https://basescan.org/tx/0x95a84c44802d09e38ef920524f947dff0eb5a2fe972054fca97bfd989cbcea59)\n— the missing 5% is the protocol's fee.\n\nIt was asked *why does knos withhold claimed work*, and what it sold, in\n180ms, was a passage out of a session from four days earlier:\n\n> knos withholds what it knows. A second agent searching claimed work gets\n> who holds it and nothing else — the content is absent from the reply, not\n> annotated.\n> — Claude Code session 4101eeab 2026-08-31\n\nNobody re-typed that. Another agent paid a penny and a fresh process read it\nback with its source. The buyer was\n[knos-buyer](https://app.virtuals.io/acp/agents/01a063e1-914d-775c-ad42-74cff7881245),\nan agent of mine registered to prove the path executes. It is not demand.\n\n## Tests\n\n`pytest` runs the critical path only — claim, withhold, concurrency,\nno-network, three tools, private files — **21 tests in well under a minute**,\nbecause a suite you wait four minutes for is one you stop running. The whole\nsuite is `pytest -m \"\"`: **272 tests**, five to twelve minutes depending on\nwhat else the machine is doing - it was ten on the machine this was last run\non. Both\ncounts come from `pytest --collect-only -q`, so\n`pytest --collect-only -q -m \"\" | tail -1` is the check. The contract has\n**9 more**: `cd contracts && forge test`.\n\nIncluding the ones that would catch a lie:\n\n- **[test_no_network.py](https://github.com/drexthealpha/Knos/blob/main/tests/test_no_network.py)** breaks `socket.connect`,\n `bind` and `getaddrinfo`, then reads a repo, answers questions, writes,\n claims, withholds and overrides. Nothing reaches for the network, and the\n guard itself is tested so the test cannot pass by doing nothing.\n- **[test_private.py](https://github.com/drexthealpha/Knos/blob/main/tests/test_private.py)** asks the search layer directly,\n with an agent's identity, for a private path. Nothing comes back.\n- **[test_memory.py](https://github.com/drexthealpha/Knos/blob/main/tests/test_memory.py)** has a second process write a\n conflict, rejected by the schema rather than by Knos.\n- **[test_recall.py](https://github.com/drexthealpha/Knos/blob/main/tests/test_recall.py)** writes as one agent and recalls\n in a separate, fresh process.\n\n## What it cannot do\n\n- **Without `knos guard --install`**, a claim withholds what Knos knows and\n nothing more: it does not stop an agent editing a file. That is the honest\n limit of MCP, which gives a server no way to see an edit, let alone refuse\n one.\n- **With the guard**, the refusal covers the edit in Claude Code, Cursor and\n OpenCode — and only those three, through their hook systems, which are not\n MCP. Claude Desktop has no hooks and is not covered. Nothing covers an\n editor a person types in themselves, or `sed`, or any tool that never asks.\n- The guard reads **only the rules a machine can check**: a prohibition with a\n path in backticks. \"Never edit `src/generated/`\" is enforced; \"write\n idiomatic code\" is not, and Knos does not guess at what it might mean.\n- The guard **fails open**. If the store cannot be read, the edit is allowed.\n A broken install standing between somebody and their own repository is a\n worse failure than the collision the guard exists to prevent.\n- Claude Code and Cursor only. No Gemini CLI or Codex history yet.\n- It does not write the answer for you, and it does not watch files. Run\n `knos point` again to catch up.\n- **Retrieval is lexical, not semantic.** Sibyl searches with SQLite FTS5, so\n Knos finds passages containing your words and ranks those. Ask about\n something the sessions never discussed and you get confident, well-sourced\n passages that share a word with your question and nothing else: \"why did we\n drop redis\" matches every note about *dropping* something. Ask in the words\n the work was done in and it is sharp. There are no embeddings at any Sibyl\n tier — the paid tier adds summarising and a learning loop, not search.\n- 5 MB per repo.\n- Four jobs have been traded through the Virtuals provider, all bought by a\n test agent of mine. Nobody else has bought anything.\n\n## Contributing\n\n[CONTRIBUTING.md](https://github.com/drexthealpha/Knos/blob/main/CONTRIBUTING.md) has the three edits an agent adapter takes\nand the test to copy. `pytest` runs the critical path in about 25 seconds;\n`pytest -m \"\"` runs all of it in about four minutes, against throwaway stores.\n\n## Prior work\n\nKnos is not a fork and not a clone. There is no earlier repository, no\nupstream project, and no pre-existing memory layer that Sibyl was added to.\nEvery line here is original work under MIT, and the commit history is the\nwhole record.\n\nThe core was written locally before the window and first published on\n1 September; everything after is dated in the log.\n\n**Dependencies, and what each is for.** Sibyl Memory\n(`sibyl-memory-client`) is the store, and it is load-bearing — see [What\nbreaks without the store](#what-breaks-without-the-store). The MCP Python\nSDK provides the server. `universal-ctags` is optional; without it Knos\nfalls back to a reader it carries itself. The Virtuals ACP SDK and the\n`x402` client are used only by `agent/`, which is the commerce leg rather\nthan the product.\n\n## The name\n\nKnos is pronounced like *knows*, and the crow is the reason. Crows cache food\nin thousands of places, remember which caches they made, and remember which\nother crows were watching when they made them — then move the ones that were\nseen. Memory, and knowing who else is in your business. A group of them is\ncalled a murder, which is either apt or a warning, depending on how many\nagents you are running.\n\n## Licence\n\nMIT.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_94":95,"_96":97,"_98":99,"_100":101,"_102":-5,"_103":104},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_92":81,"_93":81},"ratingAvg","reviewCount","topics",[],"license","MIT","language","Python","registryName","io.github.drexthealpha/knos","homepage","packages",[105],{"_106":107,"_108":21,"_71":72},"registryType","pypi","identifier","ENV",{"_111":112,"_113":114,"_115":116},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]