Metadata-Version: 2.5
Name: knos
Version: 0.1.4
Summary: One local memory every coding agent on the machine shares — and it knows which of them is in your code right now.
Project-URL: Homepage, https://github.com/drexthealpha/Knos
Project-URL: Repository, https://github.com/drexthealpha/Knos
Project-URL: Issues, https://github.com/drexthealpha/Knos/issues
Author-email: drexthealpha <zulibro1999@gmail.com>
License: MIT License
        
        Copyright (c) 2026 knos contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,coordination,local-first,mcp,memory
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Requires-Dist: mcp>=2.0
Requires-Dist: rich>=13
Requires-Dist: sibyl-memory-client>=0.7.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: flask>=3; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: x402[evm]>=2.21; extra == 'dev'
Description-Content-Type: text/markdown

# Knos

<!-- mcp-name: io.github.drexthealpha/knos -->

[![Knos MCP server](https://glama.ai/mcp/servers/drexthealpha/Knos/badges/score.svg)](https://glama.ai/mcp/servers/drexthealpha/Knos)

**Two contributors, or two agents, changing the same thing without knowing
it. Knos is the record of who is on what, and it refuses to answer about
work somebody else has already taken.**

Start with the pull request check. One file in your repo, nothing installed,
never fails a build:

```yaml
# .github/workflows/knos-claims.yml
on: [pull_request]
permissions: { contents: read, pull-requests: write }
jobs:
  claims:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: drexthealpha/Knos/action@v0.1.4
```

It reads `.knos/decisions.md` — a file a maintainer commits — and comments
when a branch touches work somebody has claimed or a decision already
recorded. It exits 0 on every path, including every failure path
(`pytest tests/test_shared_repo.py -k never_returns_non_zero`). The tag is
pinned rather than a branch, so what runs in your CI is a fixed file you can
read: `git show v0.1.4:action/knos_pr_check.py`.

`pull_request_target` works too, if you want the check on pull requests from
forks: the Action reads only the committed `.knos/decisions.md` and the pull
request's own title, body and file list, and never checks out or runs
anything from the head branch.

### The whole loop, in under a minute

```bash
pip install knos && knos connect     # once, per machine
knos claim "the parser"              # agent A takes it
# ask any other agent about the parser — it is refused, and told who has it
knos done                            # give it back
knos export                          # writes .knos/decisions.md, commit it
```

Claim, be refused, release, export. The Action then does the same thing on a
pull request, for people who have never installed Knos.

All of it runs without an editor open, as two real processes against one
store: `python scripts/withhold.py`. The other half of the proof is
`python scripts/gate.py`, which deletes the store and asserts that both the
withholding and the answers die with it —
[scripts/README.md](scripts/README.md).

Under it is a local MCP server: three tools over stdio — `search`, `about`,
`remember`. No HTTP server, no ports, no account, no model download, no repo
to register, and [no network connection at all](tests/test_no_network.py):
that last one is a test, not a promise.

`knos connect` adds Knos to **Claude Code**, **Claude Desktop**, **Cursor**
and **OpenCode** — whichever you have, each in the shape it reads
(`mcpServers` for the first three, `mcp` with `"type": "local"` for
OpenCode). For Claude Code it runs `claude mcp add --scope user`, which
registers the server with the session you are already in, so **its tools work
immediately with nothing to restart**.

For the other three, `knos connect` writes the config and takes a backup, and
then there is exactly one thing left to do:

| Client | What is left | Why |
|---|---|---|
| Claude Code | nothing | `claude mcp add --scope user` registers with the running session |
| Cursor | **Quit Cursor and open it again** (Ctrl/Cmd+Q, then reopen) | reads `~/.cursor/mcp.json` at startup; no command registers a server with a running instance |
| Claude Desktop | **Quit and reopen it** — closing the window is not enough, it keeps running in the tray | same |
| OpenCode | **Exit and start it again** (Ctrl+C, then `opencode`) | `opencode mcp add` exists but is interactive, and its docs describe no reload for a running session |

Every file it touches is copied to `<name>.before-knos` first, and
`knos connect` prints the restart line for each client that needs one —
quit the app and start it again, because nothing in the MCP spec lets a
server register itself with a session that is already running.

<details>
<summary>Other ways in — Claude Desktop extension, Claude Code plugin, or by hand</summary>

**Claude Desktop:** download `knos.mcpb` from
[Releases](https://github.com/drexthealpha/Knos/releases) and double-click it.

**Claude Code plugin:**

```
/plugin marketplace add drexthealpha/Knos
/plugin install knos@knos
```

**By hand** — `knos connect --print` shows the JSON, or add it yourself:

```json
{ "mcpServers": { "knos": { "command": "python", "args": ["-m", "knos.mcp"] } } }
```

Every path runs the same `python -m knos.mcp`, so `pip install knos` comes
first whichever you pick.
</details>

The first thing an agent asks about a repo reads it. Seven cold runs each,
whole 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),
2.0s on goose (1.8-3.4), 3.1s on the Linux kernel (3.0-6.8)** — 93,703 tracked
files. What it does in that time is one `git log`, your `CLAUDE.md`, and the
transcripts of past sessions in that tree, written to SQLite. It happens once. Every question after it is
under 0.2s, and every agent you have shares the result.

## What a claim does here

Claude Code is rewriting the risk guard. You ask Cursor about it.

Every tool in the table below answers, and Cursor gives you a confident plan
built on the version that was on disk five minutes ago. Knos does this
instead:

```
Withheld. risk guard (held by Claude Code) is being worked on right now,
so knos is not the place you find out about it. Ask them, or work on
something else.
```

Not a warning attached to the answer — **no answer**. Your agent can still
take it, by saying why, and the reason is written down under its name where
you will read it. `knos done` releases it, and so does half an hour.

Every cell below comes from that tool's own README or documentation page, so
you can check each one:

| | To install | MCP tools | Needs | Refuses to answer about work another agent claimed |
|---|---|---|---|---|
| `CLAUDE.md` + worktrees | — | — | nothing | no |
| [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 |
| [mcp-local-memory](https://github.com/Beledarian/mcp-local-memory) | npx entry in your config | 18 | may download an embedding model | no |
| [Engram](https://github.com/Gentleman-Programming/engram) | `brew install` + `engram setup <agent>` | 16 | nothing — one binary | not addressed |
| [MemPalace](https://github.com/MemPalace/mempalace) | `uv tool install mempalace` + `init` + `mine` | 45 | ~300 MB embedding model | no — separate wings per agent |
| [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 |
| [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" |
| [CoordMCP](https://glama.ai/mcp/servers/siddiquesahabaj/CoordMCP) | `pip install coordmcp` | **52** | a coordination server running | no — `lock_files` blocks edits, not reads |
| [Memryzed](https://github.com/memryzed/memryzed) | `curl -fsSL https://memryzed.com/install.sh \| bash` | 9 | nothing — one SQLite file | not addressed |
| [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 |
| **Knos** | **`pip install knos && knos connect`** | **3** | **nothing** | **yes** |

Knos is not the only tool with claims, and that column would be dishonest if
it implied so. Vibsync, CoordMCP, AgentRoom and Agent Claim MCP all let an
agent claim something; agentmemory has leases. The difference is what a claim
*does*. Everywhere else it is a signal about a file, which an agent may check
before editing and may ignore — Vibsync says so itself, and CoordMCP's locks
stop edits while the memory stays fully readable. Knos changes what the memory
says: ask about work someone else claimed and there is no answer to act on,
and the claim is bound to the connection that made it, so an agent naming
itself the holder is still refused.

Two of these are worth your attention for reasons other than that column.
Memryzed is local, keyless and one SQLite file — the same shape as Knos, with
more recall tools and no coordination. Vibsync is the only one that shares a
claim across machines, which Knos does not: a committed `.knos/decisions.md`
is as far as a claim travels here.

Knos is not trying to out-remember these tools. It is trying to be the one
that speaks up while two agents are in the same code, and to cost you two
commands and three tools to find out.

## One agent is enough to see it

```bash
knos claim "the parser"
```

Ask your agent about the parser. It is refused, and tells you so. `knos done`
and it answers again. That is the whole mechanism, in two commands.

```mermaid
flowchart TD
    P["pip install knos<br>knos connect"] --> CC["Claude Code"]
    P --> CU["Cursor"]
    P --> CD["Claude Desktop"]
    P --> OC["OpenCode"]

    CC -->|"first question reads the repo"| S[("one SQLite file<br>no server, no model")]
    CU --> S
    CD --> S
    OC --> S

    R["CLAUDE.md, AGENTS.md, ADRs<br>commits, past sessions"] --> S
    W["every worktree of this repo"] --> S

    S -->|"answers, with the source"| CC
    S -->|"withheld - Claude Code is on it"| CU

    style S fill:#1f2933,stroke:#7b8794,color:#ffffff
    style P fill:#e8f0fe,stroke:#4a6fa5,color:#111111
    style R fill:#f5f5f5,stroke:#999999,color:#111111
    style W fill:#f5f5f5,stroke:#999999,color:#111111
```

Every arrow above is a command you can run: the withheld one is
`knos claim "the parser"` then asking a second agent, and
`pytest tests/test_intent.py -k withholds_the_answer` is the same thing as a
test.

## Share it with the repo, not a server

Everything above is local. Two things, though, exist nowhere a teammate can
reach — what somebody decided, and what somebody is working on right now. So
those go in the repository, as a file you commit:

```bash
knos export        # writes .knos/decisions.md
git add .knos && git commit -m "share decisions"
```

That one file is the whole mechanism. It is markdown, it diffs in review, and
three different kinds of reader consume it without installing anything:

- **A teammate clones and asks.** `.knos/decisions.md` is one of the decision
  records Knos already reads, so a clean clone answers from it on its first
  question — no install, no sync, no account, no server between the two
  machines (`pytest tests/test_shared_repo.py -k second_clean_clone`).
- **Every agent on their machine reads it too**, through the same three MCP
  tools, on the same first question. A contributor who has never heard of
  Knos still gets your decisions, because their agent asks and the file is
  already in the checkout.
- **CI reads it on a pull request** and says so when the branch touches work
  somebody has claimed (`pytest tests/test_shared_repo.py -k ci_warns`).

```yaml
# .github/workflows/knos-claims.yml
on: pull_request
permissions: { contents: read, pull-requests: write }
jobs:
  claims:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: drexthealpha/Knos/action@v0.1.4
```

The comment is a heads-up, never a failure — `action/knos_pr_check.py`
exits 0 on every path, including when it finds a conflict and when it
crashes.

**It runs both ways, and that is the part that compounds.** The teammate who
cloned runs `knos export` too. Their decisions and their claims land in the
same file, you pull, and your agents read what they decided while you were
not looking. Every contributor writes to the file and reads from it, so it
holds more after each one than before. The repository is the shared object:
there is no database of ours, no protocol to adopt, and no server to pay
for.

Secrets do not travel: a note about `.env` is filtered out of the exported
file by the same check that hides `.env` from an agent
(`pytest tests/test_shared_repo.py -k private_note`).

**Nothing outside this repository has adopted it yet.** The loop is
implemented and tested, six tests in `tests/test_shared_repo.py`. That is a
mechanism that works, not a network that exists.

## Who else has written this problem down

Nothing here is about Knos. These are other people's open issues, in their
own repositories, filed before they had heard of it.

GitHub issues created since 1 January 2026 that use the phrase `"multiple
agents" "same file"` number **1,556**; `"two agents"` in a title or body
returns **31,411**. Most of that is unrelated prose. The ten below are ones
read individually: every one is open, in a repository between 1,212 and
388,747 stars, and describes two agents working over each other.

| Repository | Stars | Opened | Issue |
|---|---|---|---|
| openai/codex | 121,228 | 2026-08-03 | [Add a cross-agent intent map to prevent overlapping edits](https://github.com/openai/codex/issues/36719) |
| openai/codex | 121,228 | 2026-08-06 | [Automatically isolate and coordinate concurrent writes across chats and agents](https://github.com/openai/codex/issues/37226) |
| anthropics/claude-code | 143,931 | 2026-09-03 | [Subagent exceeded scope and executed unauthorized git commit](https://github.com/anthropics/claude-code/issues/91872) |
| openclaw/openclaw | 388,747 | 2026-08-19 | [AgentSelectionRequiredError floods logs under explicit multi-agent ownership](https://github.com/openclaw/openclaw/issues/126360) |
| openclaw/openclaw | 388,747 | 2026-08-13 | [Shared state WAL checkpoint copies index pages over SQLite page 1](https://github.com/openclaw/openclaw/issues/123327) |
| CopilotKit/CopilotKit | 37,180 | 2026-06-24 | [Agents mutate a shared singleton per-request; concurrent users leak system prompts](https://github.com/CopilotKit/CopilotKit/issues/5659) |
| omnigent-ai/omnigent | 9,657 | 2026-07-28 | [Session-state writes race under concurrent updates: lost updates and orphan rows](https://github.com/omnigent-ai/omnigent/issues/3402) |
| microsoft/winappCli | 1,212 | 2026-08-17 | [Cooperative UI turns for concurrent winapp UI agents](https://github.com/microsoft/winappCli/issues/764) |
| microsoft/winappCli | 1,212 | 2026-08-17 | [Add worktree-isolated identity to `winapp run`](https://github.com/microsoft/winappCli/issues/763) |
| Vexa-ai/vexa | 2,745 | 2026-09-03 | [Two stores, neither authoritative](https://github.com/Vexa-ai/vexa/issues/1510) |

Two of those — `openai/codex` #36719 and #37226 — ask for a record of what
each agent intends to edit, so that two of them do not edit the same thing.
That is the mechanism in [What a claim does here](#what-a-claim-does-here).
Both are open.

Check the two counts, and that these are still open, with the GitHub CLI:

```bash
gh api -X GET search/issues -f 'q=is:issue "multiple agents" "same file" in:body created:>2026-01-01' --jq .total_count
gh api repos/openai/codex/issues/36719 --jq .state
```

### One repository that coordinates agents through a GitHub issue today

`tsz-org/tsz` runs its agents against a claim board:
[issue #17314](https://github.com/tsz-org/tsz/issues/17314), **1,133
comments** at the time of writing, the successor to
[#15994](https://github.com/tsz-org/tsz/issues/15994), which was forked after
it hit the 2,500-comment cap. Agents post `CLAIM`, `DONE`, `DROP` and `BLOCK`
lines and are expected to read the board before starting. Its standing
gotchas record the failures that follow: sessions that end on a live claim
with no closing record, and two claims naming one defect in different words.

That is the same coordination record Knos keeps, kept by hand in a comment
thread, at a scale where reading it before every edit stops being possible.

**No repository outside this one has adopted Knos.** The issues above are
evidence that the problem is real and written down by other people. They are
not evidence that anyone has adopted this answer to it.

## Check any of it in under a minute

Nothing below is a claim. Each row is a command; run it and see.

| What | How to check it yourself |
|---|---|
| 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. |
| 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 |
| 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 |
| 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` |
| Every worktree of a repo is one memory | `pytest tests/test_worktrees.py` |
| 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 |
| Secrets are invisible, not redacted | `pytest tests/test_private.py` — the search layer is asked directly, with an agent's identity |
| What dies when you delete the store | `pytest tests/test_sibyl_is_load_bearing.py -k number_status_prints` |
| Three MCP tools, no more | `pytest tests/test_recall.py -k three_tools_are_listed` |
| 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 |
| A crashed agent cannot hold work forever | `pytest tests/test_intent.py -k lapses` |
| The pull request check can never fail a build | `pytest tests/test_shared_repo.py -k never_returns_non_zero` |
| CI comments on decisions, not only claims | `pytest tests/test_shared_repo.py -k reports_decisions` |
| A full store refuses a claim rather than dropping it | `pytest tests/test_sibyl_is_load_bearing.py -k full_store` |
| `knos status` says how many claims are held | `pytest tests/test_sibyl_is_load_bearing.py -k counts_the_claims` |
| `knos connect` names the exact restart per client | `pytest tests/test_cli.py -k exact_restart` |

Cost: `pip install knos`. No account, no key, no server, no model download,
no network request, and a 5 MB free-tier cap per repo.

## Everything else, briefly

Every answer names where it came from — a commit, a session and a date, or a
file and a line. Knos has no model: it does not summarise and it does not
guess, it finds what somebody actually said.

```
$ knos ask "what are the rules here?"

Ask before adding a dependency. The build is the product.
    AGENTS.md:3
Every change ships with a test. A green run you did not watch is not green.
    CLAUDE.md:8
```

| Source | From |
|---|---|
| Your rules | `CLAUDE.md`, `AGENTS.md` |
| Decisions in the repo | `.knos/decisions.md`, `DECISIONS.md`, `WORKLOG.md`, `docs/adr/*.md`, `docs/decisions/*.md` |
| Agent sessions | Claude Code transcripts, Cursor's history |
| Commits | `git log` |
| Code structure | read by Knos itself, or [universal-ctags](https://github.com/universal-ctags/ctags) when you have it |
| What you tell it | `knos remember` |

### What is covered, and what is not

Knos is wired into **4 clients** and reads the past session history of **2**.
Both numbers are the honest ones:

| Client | MCP tools | Reads its past sessions |
|---|---|---|
| Claude Code | yes, no restart | yes |
| Cursor | yes | yes |
| Claude Desktop | yes | no |
| OpenCode | yes | no |
| Hermes Agent | via [knos-hermes](https://github.com/drexthealpha/knos-hermes) | no |
| Gemini CLI, Codex, Windsurf, Aider, Continue | no | no |

Wiring a client is three edits and a test — [CONTRIBUTING.md](CONTRIBUTING.md)
has them, with OpenCode as the worked example. A session reader is about 40
lines: **Codex CLI and Gemini CLI are the two missing ones**, each a small
parser plus one test, written up in
[`.github/GOOD_FIRST_ISSUES.md`](.github/GOOD_FIRST_ISSUES.md).

**Knos does not have memory of every local workflow, and does not claim to.**

`.env`, `*.pem`, `id_rsa`, `.ssh`, `.aws` and twelve more are private the
moment Knos reads a repo, without being asked. Private means invisible, not
redacted: an agent asking about one is told nothing at all — no result, no
count, no "2 hidden".

**Worktrees.** Keep them; they do a different job, and Knos treats every
worktree of a repo as one memory anyway. Read the repo in one tree and every
other tree can answer. Claim in one and the agents in the others are held off.

The whole mechanism is one git command. `git rev-parse --show-toplevel`
returns the worktree root, so every worktree looks like a different project;
`git rev-parse --git-common-dir` returns the git directory the worktrees
share, which is identical across all of them. Knos keys the store on the
second. Tools that key on the first fragment a repo's memory once per
worktree — [that bug, in another
tool](https://github.com/rohitg00/agentmemory/issues/515). Check it:
`pytest tests/test_worktrees.py`.

**A claim lapses after 30 minutes.** An agent that crashes mid-change
never calls `knos done`. If the claim outlived the process, that work would
be unaskable until a person noticed and cleared it by hand. Instead the hold
expires on its own, and the next agent to ask gets a real answer. Taking a
claim is a compare-and-swap, not a blind write, so two agents reaching for
the same work in the same second do not both believe they have it: one wins,
the other is told who holds it. Check both:
`pytest tests/test_intent.py -k "lapses or two_processes"`.

**Five tiers, one file, a hard 5 MB cap.** Sibyl's schema is not a black box
Knos writes blobs into — it uses the tiers for what they are. Live claims go
in HOT, one row per topic, overwritten rather than appended. Decisions and
files go in WARM. History goes in COLD, append-only. The whole thing is
capped at 5 MB by Sibyl's free tier, and `knos status` prints the size and
says `nearly full` from 4 MB, so a store that is filling up tells you before
it stops taking writes rather than after
(`pytest tests/test_sibyl_is_load_bearing.py -k cap_and_warns`). At 5 MB a
claim is **refused in words, not dropped**: an agent that thinks it holds
work it does not is the exact failure this whole feature exists to prevent
(`pytest tests/test_sibyl_is_load_bearing.py -k full_store`).

**Commands.** `knos ask`, `knos claim`, `knos done`, `knos status`,
`knos export`. `knos help` lists the rest. Nothing runs itself: no watcher,
no daemon, no schedule.

### Speed, on the one question this is for

"What was decided, and is anyone on it?" — warm, whole process, median of 7:

| | Knos | `git log --all -S` |
|---|---|---|
| small repo | 960ms | **33ms** |
| Linux kernel (93,703 files) | **920ms** | 28,289ms |

Git wins on a small repo and it is not close. Knos's time is flat with repo
size because it reads an index rather than walking history; git's grows with
it. On the kernel that is 30x, and most of Knos's 900ms is Python starting up.

**Knos is not faster than git at anything git is for**, and a cold first read
of a large repo is slower than either — 3.1s median, stated above.

**What agents actually read.** A study of 557 agent sessions and
33,097 pull requests found that **60.5%** of everything coding agents do with
documentation happens in instruction files and their own notes — `CLAUDE.md`,
`AGENTS.md`, plans, scratch notes — against 10.6% for classical docs and 1.3%
for API references ([Gao & Chen, 2026](https://arxiv.org/abs/2608.20195)).
The same paper says the link between what agents consult and what they edit
is unresolved, so this measures where agents spend their documentation time,
not that Knos is needed. What is separately true: none of those files can say
who is reading them, or what another agent is changing right now.

## What happens when you delete the memory

One SQLite file at `~/.knos/<repo>/memory.db`, via
[Sibyl](https://github.com/Sibyl-Labs/Sibyl-Memory), **capped at 5 MB per
repo** — Sibyl's free tier, and Knos runs it unactivated, so there is no
account to make and no cap to raise. Sessions and commits are read newest
first, so when a repo fills, what you have is the recent end of both and the
older end was never read. Nothing already stored is evicted or truncated, and
`knos status` says `nearly full` from 4 MB. The Linux kernel filled 0.3 MB.

Nothing leaves this machine — Knos makes no network request. Delete that
file and:

| | Gone forever | Why |
|---|---|---|
| What you told it (`remember`) | **yes** | it existed nowhere else |
| Every claim, and the withholding | **yes** | same |
| Who stood down for whom, every override | **yes** | same |
| Your commits, `CLAUDE.md`, past sessions | no — re-read | they are your files, not Knos's |

`knos status` counts that first row for you, so you never take it on trust:

```
journal    330 things learned
             0 of them exist nowhere else - told, claimed, stood down
             delete the store and only those go; the rest is re-read from your repo
```

Ten seconds to prove it: claim something, watch an agent be refused, delete
the file, ask again. Nothing was ever held.

More on the five tiers, why a claim expires, and how a hold is bound to a
connection so an agent cannot borrow somebody else's name:
[docs/core-flow.md](docs/core-flow.md).

## The two onchain parts, and exactly what they are

Both are optional. Knos works with neither, and nothing on the read or answer
path touches a network — that is what `pytest tests/test_no_network.py`
checks.

### Base: sharing one folder with a teammate

```bash
knos share ./src --with alice.base.eth
knos unshare ./src --with alice.base.eth
```

**What it does.** Their agent can read that folder and nothing else. The
record of who may read what is [Access.sol](contracts/src/Access.sol) on Base
Sepolia, so neither machine has to trust the other's copy of the answer.
Testnet, so it costs nothing.

**What it does not do.** It does not move your memory anywhere — the store
stays on your disk. It does not encrypt anything. It is one permission bit
per person per folder, not a sync protocol.

**How to verify it.** Two commands and one number each way:

```bash
python -c "from knos import team; o=team.identity('owner').address; m=team.identity('teammate').address; \
team.share('crates','teammate'); print(team.may_read(o,'crates',m)); \
team.unshare('crates','teammate'); print(team.may_read(o,'crates',m))"
# True
# False
```

Or read it without running anything: contract
[`0x955fa320…6E52`](https://sepolia.basescan.org/address/0x955fa320D60D9172CF048141ed7eEE442da66E52),
and one full cycle —
[deploy](https://sepolia.basescan.org/tx/0xdcc25ff7460a09a080ec32016b39121b6a34b741f03411bcfdc2ee2a93b31d21),
[grant](https://sepolia.basescan.org/tx/0x84e11e21315b51e9e6b6453d226a44bcabf5a80f4c0085ba6f5b56ed169a92b6),
[revoke](https://sepolia.basescan.org/tx/0xb3ea6920c0a7bf7fa9dde64e6f0c2275e149f976bf20c909098a2431417adfb4).
Nine contract tests: `cd contracts && forge test`.

### Virtuals: selling one answer

**What it does.** Knos is registered on the Virtuals marketplace as a
provider with one offering: another agent pays 0.01 USDC for an answer out of
this machine's memory. The seller is [agent/offering.ts](agent/offering.ts).

[agent/bot.ts](agent/bot.ts) is that same agent with a chat face, in one
process: it answers ACP jobs, it answers `/ask` out of the same store, and
`/brief` buys something over x402 on Base and writes what it bought back with
`knos remember`, so the next agent on the machine gets it without paying.
Every one of those paths reads or writes the same SQLite file —
`python scripts/gate.py` deletes it and none of them work.

Started with no Telegram token it reads commands from the console, so the
whole thing runs without an account:

```
$ npm --prefix agent run bot -- /status
  hot        nothing in progress               one each, expires after 30 min
             0 claims held right now - nothing is being withheld
             2.2 MB of 5 MB used
```

**The x402 half is live on Base mainnet.** `/brief BTC` pays 0.01 USDC to
[x402-seller](https://x402-seller-m8nx.onrender.com)'s market-regime endpoint
and writes what it bought into the store with its receipt. Five settled so
far, signed by `0xEca35a0C…48C1`:
[`0x2ce6af5c…`](https://basescan.org/tx/0x2ce6af5c1c223a5b1395cbae719a96d7f1ded74fd90f909375142f9e4a14d9ca),
[`0x20983f7b…`](https://basescan.org/tx/0x20983f7ba5afc2cc96da402e1509e8f267c15e4068048f6397bee4bb13537d04).
The client is [src/knos/buy402.py](src/knos/buy402.py), which signs with the
keystore knos made itself — there is no private key in any config file.

Two routes on that seller, `/markets` and `/signal`, return 502 after the
402. They cost nothing (the payment never settles) but they are why `/brief`
is the only route wired in.

**What it does not do.** There is no evaluator and no reputation system, and
**every job traded through it was bought by a test agent of mine, not by a
customer.** It is off by default and runs only when you start it.

**How to verify it.** The agent page is public — open
[app.virtuals.io/acp/agents/01a05b97…](https://app.virtuals.io/acp/agents/01a05b97-a776-760a-9165-e9893e4091dc)
and you will see the registration without installing anything. Job 75659 is
on Base mainnet, in two legs, neither of which needs an account to read:
[buyer pays 0.01 USDC into escrow](https://basescan.org/tx/0x756b867b2b1165bfe674025a82d21cd765378a40ab226274bd555abf0065bd64),
then [escrow releases 0.0095 to the provider](https://basescan.org/tx/0x95a84c44802d09e38ef920524f947dff0eb5a2fe972054fca97bfd989cbcea59)
— the missing 5% is the protocol's fee.

It was asked *why does knos withhold claimed work*, and what it sold, in
180ms, was a passage out of a session from four days earlier:

> knos withholds what it knows. A second agent searching claimed work gets
> who holds it and nothing else — the content is absent from the reply, not
> annotated.
> — Claude Code session 4101eeab 2026-08-31

Nobody re-typed that. Another agent paid a penny and a fresh process read it
back with its source. The buyer was
[knos-buyer](https://app.virtuals.io/acp/agents/01a063e1-914d-775c-ad42-74cff7881245),
an agent of mine registered to prove the path executes. It is not demand.

## What breaks without the store

Every capability below reads or writes the one SQLite file. The middle column
is the command that exercises it; the right column is where it touches the
store. `python scripts/gate.py` deletes the file and asserts the first three
rows stop working.

| Capability | Run it | Where it touches the store |
|---|---|---|
| A claim is taken, once, atomically | `knos claim "the parser"` | `Memory.claim_if_free` — compare-and-swap into HOT state, `src/knos/memory.py` |
| A second agent is refused | ask any other agent about it | `mcp.search` → `_being_worked_on` reads HOT, `src/knos/mcp.py` |
| Who stood down, and who overrode | `knos status` | COLD journal via `Memory.stood_down` / `_took_it_anyway` |
| What you told it | `knos remember "..."` | `Memory.record` → journal, `Memory.note_thing` → WARM entity |
| Decisions shared with the repo | `knos export` | WARM + HOT read out into `.knos/decisions.md` |
| A brief bought over x402 | `/brief BTC` in the bot | `knos remember` after payment — the receipt exists nowhere else |
| An ACP deliverable | a buyer funds a job | `agent/offering.ts` shells to `knos ask`, which reads the store |
| How full it is, and what dies | `knos status` | `Memory.size_mb`, `Memory.only_here` |

The claim lives in HOT because it is about *now* and is overwritten, not
appended. Decisions live in WARM because they are named things replaced in
place. History lives in COLD because it is append-only. That is Sibyl's
schema used as intended rather than as a key-value bucket, and `knos status`
prints the tiers by name.

## Tests

`pytest` runs the critical path only — claim, withhold, concurrency,
no-network, three tools, private files — **11 tests in about 25 seconds** on an idle machine,
because a suite you wait four minutes for is one you stop running. The whole
suite is `pytest -m ""`: **214 tests**, about four minutes. The contract has
**9 more**: `cd contracts && forge test`.

Including the ones that would catch a lie:

- **[test_no_network.py](tests/test_no_network.py)** breaks `socket.connect`,
  `bind` and `getaddrinfo`, then reads a repo, answers questions, writes,
  claims, withholds and overrides. Nothing reaches for the network, and the
  guard itself is tested so the test cannot pass by doing nothing.
- **[test_private.py](tests/test_private.py)** asks the search layer directly,
  with an agent's identity, for a private path. Nothing comes back.
- **[test_memory.py](tests/test_memory.py)** has a second process write a
  conflict, rejected by the schema rather than by Knos.
- **[test_recall.py](tests/test_recall.py)** writes as one agent and recalls
  in a separate, fresh process.

## What it cannot do

- A claim withholds what Knos knows. It cannot stop an agent editing a file —
  nothing on your machine can, short of file permissions. If you need that,
  use a worktree.
- Rules are enforced **only on what Knos mediates**: recall, `remember`, and
  the claim/withhold path. Knos cannot make a foreign runtime obey your
  `CLAUDE.md`; it can only decline to be the source of truth, and say who to
  ask. No MCP server can do more than this: the protocol gives a server no
  way to intercept an edit.
- Claude Code and Cursor only. No Gemini CLI or Codex history yet.
- It does not write the answer for you, and it does not watch files. Run
  `knos point` again to catch up.
- **Retrieval is lexical, not semantic.** Sibyl searches with SQLite FTS5, so
  Knos finds passages containing your words and ranks those. Ask about
  something the sessions never discussed and you get confident, well-sourced
  passages that share a word with your question and nothing else: "why did we
  drop redis" matches every note about *dropping* something. Ask in the words
  the work was done in and it is sharp. There are no embeddings at any Sibyl
  tier — the paid tier adds summarising and a learning loop, not search.
- 5 MB per repo.
- Four jobs have been traded through the Virtuals provider, all bought by a
  test agent of mine. Nobody else has bought anything.

## Contributing

[CONTRIBUTING.md](CONTRIBUTING.md) has the three edits an agent adapter takes
and the test to copy. `pytest` runs the critical path in about 25 seconds;
`pytest -m ""` runs all of it in about four minutes, against throwaway stores.

## Licence

MIT.
