Knos is a shared, local memory server for coding agents: it records facts and claims about a repo, withholds claimed work from other agents, and refuses edits before they land.
search: query past sessions, commits, and code structure; results name their source, and work claimed by another agent is withheld (you get the holder's identity, not the answer).
about: get what is known about a specific file, person, or topic.
remember: write a fact to shared memory so future sessions in any agent can read it; set claiming to take ownership of work, which withholds that topic from other agents until you finish or the hold expires.
Optional override: search can be called with override to request withheld information, and the reason is journaled against your name.
On-behalf-of scoping: on_behalf_of restricts a search to only the folders a teammate was actually shared.
Enforced coordination: the store backs refusals, blocks filesystem writes before they happen, prevents double-granting of claimed work, and gates paid purchases.
Check every claim on this page without installing anything: drexthealpha.github.io/Knos — the collision study, the eight arms, the money gate and all twelve on-chain receipts, each number read live out of the JSON the scripts wrote.
One shared memory for every coding agent on your machine. Two agents, or two people, change 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 taken, and refuses the edit before the write lands.
pip install "git+https://github.com/drexthealpha/Knos"
knos demoFrom the repository: PyPI is the last cut
release and trails main.
Fifty seconds on a throwaway repo, ninety the first time. A claim, a second agent refused, an edit blocked before the write, a purchase that costs nothing the second time, a reversed decision holding the work under it, a process that has never seen the repo reading it all back with its own pid and the commit hash on screen — and then the store is deleted and you watch every one of those stop.
Every line it prints is a real call into the real code. The evidence page is a page about the product, not part of it: nothing on the read path touches a network, and that is a test rather than a promise. There is no hosted knos, and there will not be one.
Related MCP server: memmd-mcp
Knos | |
Listed in the MCP directory | yes — awesome-mcp-servers#13480, merged by the owner into a 94.5k-star index |
Code merged by third-party maintainers | 5 merged, 3 still open — the list |
Agents racing for one topic, real processes | 16, 0 double-grants in 128 attempts; 15 unshared — |
Onchain receipts that resolve | 12 of 12, 9 on Base mainnet with USDC — |
Money spent on work that got dropped | $0.044 to $0.000 — the gate reads who is asking, |
Hold length learned per agent | 29% less time blocked — |
Evidence regenerated on a clean machine | daily in public CI — last run reproduced every figure identically |
Record of who overrode whom | chained per writer — |
A rule deleted from | stops being quoted — |
Refusal that stops a filesystem write | yes, and renaming the file does not get past it |
Retained users | none. The full ledger, including 34 pull requests that failed |
The Action — zero install, never fails your build. It reads the
.knos/decisions.md a contributor commits and comments on a pull request that
touches claimed work. Drop this in .github/workflows/knos-claims.yml:
on: [pull_request]
jobs:
claims:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: drexthealpha/Knos/action@v0.1.8The library — if you already ship a tool, import the claim instead of running ours. No MCP, no CLI, no daemon:
from knos.core import Claims
with Claims(repo=".", who="my-agent") as claims:
took, holder = claims.take("the parser")
if not took:
print(f"{holder['who']} has it")The server — pip install knos && knos connect puts it in front of Claude
Code, Cursor, OpenCode and Claude Desktop, with four tools: search,
about, remember and done - the last of which is how an agent says it
has finished, so the others stop waiting on work already done.
Everything. That is the point, and it is a test rather than a claim —
pytest tests/test_sibyl_is_load_bearing.py.
Delete memory.db and the withhold is gone, the edit is allowed, the paid
answer buys again, and the held decisions are released. There is no degraded
mode — there is no product.
flowchart TD
A["Agent A<br>rewriting the parser"] -->|"claims it"| S[("Sibyl Memory<br>one SQLite file")]
B["Agent B<br>asks about the parser"] --> S
S --> NO["withheld<br>held by Agent A, no answer"]
S --> STOP["the edit is refused<br>before the write lands"]
S --> MONEY["the purchase is refused<br>this agent abandons work"]
D["delete the file"] -.->|"all three stop"| S
style S fill:#1f2933,stroke:#7b8794,color:#ffffff
style A fill:#e8f0fe,stroke:#4a6fa5,color:#111111
style B fill:#fdf0e8,stroke:#a5744a,color:#111111
style NO fill:#fdf0e8,stroke:#a5744a,color:#111111
style STOP fill:#fdf0e8,stroke:#a5744a,color:#111111
style MONEY fill:#fdf0e8,stroke:#a5744a,color:#111111
style D fill:#f5f5f5,stroke:#999999,color:#111111,stroke-dasharray: 4 3Two of these are commands the install gives you. The rest are in the repository, so clone it first — they are scripts and tests, not product.
knos receipts # every onchain claim, resolved against Base
knos verify # nobody edited the record of who overrode whom
git clone https://github.com/drexthealpha/Knos && cd Knos
python scripts/collide.py # 16 processes, one topic, 0 double-grants
python scripts/budget.py # what the store saves when an agent abandons work
python scripts/ablation.py # 8 arms x 12 trials, each dying with the storeThe refusals themselves: pytest tests/test_intent.py tests/test_guard.py tests/test_rename_bypass.py. That the read path opens no socket:
pytest tests/test_no_network.py.
Scoring this |
|
How it works | |
Proof and receipts | |
Who wants this, and who has not | |
The long version of this page |
Both optional, both off by default. Knos runs with them switched off and nothing on the read path touches a network.
Base — purchases settle over x402 in real USDC on mainnet, and the receipt goes back into the store, so the money gate reads a Base transaction hash to decide whether to spend again.
Virtuals — a Telegram bot that is also a registered ACP provider, selling one answer out of this store.
Details and every hash: docs/VERIFICATION.md.
Every one of these is a read of the store that changes what happens next.
Delete memory.db and each line becomes the one after the arrow.
the read | decides | without the store |
whether an agent is answered at all | it answers, and two agents edit the same thing | |
whether a file is written to disk | the write lands | |
whether money moves | it buys the same answer again | |
how long the next claim survives | everyone is a stranger worth 30 minutes | |
whether work under a reversed decision is held | it proceeds on wording that was withdrawn | |
whether the record was edited | there is no record to check |
Every write and read into Sibyl is in one file, src/knos/memory.py, with
line numbers in the judge guide. The deletion test is
pytest tests/test_sibyl_is_load_bearing.py.
Knos is not a tool that happens to save things. Take Sibyl out and there is no product left to run.
The claim lives in the store, and that is the whole mechanism: one agent writes down what it is changing, and the next agent whose question touches that subject is handed the holder's name instead of an answer. The refusal is not a rule enforced somewhere else in the code — it is a read of the store, and it fails exactly when the read fails.
Three other things exist nowhere else: what you told it with knos remember,
the brief an agent paid for over x402 and wrote back, and the ACP job it sold.
Your commits and your CLAUDE.md are re-read after a delete. Those are not.
Knos is not a fork and not a clone. There is no upstream project and no pre-existing memory layer that Sibyl was added to. Every line is original work under MIT and the commit history is the whole record — written locally before the window and first published on 1 September; everything after is dated in the log.
Dependencies, and what each is for. Sibyl Memory (sibyl-memory-client)
is the store, and it is the load-bearing one. The MCP Python SDK provides the
server. universal-ctags is optional — without it knos falls back to a reader
it carries itself. The Virtuals ACP SDK and the x402 client are used only by
agent/, which is the commerce leg rather than the product.
The longer version of all three: docs/GUIDE.md.
It does not stop a determined person, and it is not access control. It knows what agents on this machine told it. It has no retained users. The ledger says so plainly, including the 34 pull requests that were the wrong idea.
MIT. The name is a Greek root for a thing known.
What is known about one thing: a file, a person, a topic.
| Name | Required | Description | Default |
|---|---|---|---|
| thing | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. 'What is known' suggests a read-only retrieval operation, which is useful, but it does not state what happens for unknown entities, whether any side effects occur, or whether special permissions/identifiers are needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no filler, and the core semantic ('what is known about one thing') is front-loaded. It earns its place without redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema present, the description is minimally adequate: it names the input concept and implies retrieval. But it leaves the parameter format ambiguous and gives no routing guidance relative to 'search' and 'remember', which are the main completeness gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only a required property named 'thing' with no description, so schema coverage is 0%. The description partially compensates by defining the parameter as a file, person, or topic, but it does not specify the expected format, identifier type, or how to distinguish between those referent kinds.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description conveys a lookup-style tool for a single referent ('What is known about one thing') and gives concrete examples ('a file, a person, a topic') that clarify the resource scope. It is distinguishable from the siblings 'search' and 'remember' by emphasizing facts about one entity rather than discovering or storing, though it does not name the siblings directly and uses the vague word 'thing'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use this tool when you need known information about a single file, person, or topic. However, there is no explicit guidance about when to prefer 'search' for broader discovery or 'remember' for storing knowledge, and the siblings are not mentioned in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write something back, so the next session in any agent knows it too.
Set `claiming` when you are about to start work on this, rather than
just noting something. Other agents are then told you have it and knos
withholds it from them until you finish or half an hour passes. Writing
a plain fact claims nothing: a note everybody can read is the point.| Name | Required | Description | Default |
|---|---|---|---|
| fact | Yes | ||
| about | Yes | ||
| claiming | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It goes beyond the schema by disclosing that claimed facts are withheld from other agents, that the claim releases when work finishes or after half an hour, and that plain facts are readable by everyone. This is meaningful, non-obvious behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded: purpose first, then only the claiming nuance that materially affects how the tool behaves. It is not bloated, though the typo 'knos' is a minor polish issue.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The essential write-and-claim semantics are well covered, and because an output schema exists, return values need not be described. However, given the locking/timeout complexity and no annotations, a complete definition should also explain the required 'about' parameter and perhaps give an example of a fact/about pair.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It thoroughly explains 'claiming' and clarifies that a 'plain fact' is a shared note, but it never defines the required 'about' parameter or the expected shape/scope of 'fact'. This partial compensation leaves one required parameter ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence identifies a concrete action — 'Write something back' so future sessions know it — and the rest clarifies that this is a shared note versus a claimed work item, which separates storing from searching. The resource is a bit vague ('something'), but the required fact/about parameters and the write-vs-claim distinction make the core purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The overall use case is implied: persist information so a future session can read it. It gives clear advice on setting 'claiming' when starting work instead of merely recording a fact, but it never explicitly contrasts this tool with the sibling tools 'search' or 'about' or states when not to use remember.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search this machine's memory of the repo: past agent sessions, commits and code structure. Every result names where it came from.
Work another agent has claimed is withheld: you get who holds it, not
the answer. Ask them, or pick up something else. If you genuinely must
have it, call again with `override` set to your reason, which is
recorded in the journal against your name.
`on_behalf_of` names a teammate when the agent is working for one. They
see only the folders they were actually shared, and nothing else.| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| override | No | ||
| on_behalf_of | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden — and it excels. It discloses the withholding behavior (you get the holder, not the answer), provenance labeling ("Every result names where it came from"), the audit side effect of override ("recorded in the journal against your name"), and the access-scoping behavior of on_behalf_of ("They see only the folders they were actually shared"). These are exactly the non-obvious behavioral traits an agent needs to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three paragraphs but front-loaded with the core purpose in the first sentence. Each paragraph has a distinct job: scope, withholding/override policy, and teammate parameter. It is slightly long, but every sentence carries substantive information and none is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists (covering return values), the description covers the tricky semantics well: search scope, source attribution, contention handling, override auditing, and teammate scoping. The main remaining gap is the undocumented limit parameter and the absence of any guidance about result ordering or what happens on empty results — minor given the overall richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does add real meaning for override (purpose + journaling side effect) and on_behalf_of (teammate context + visibility scoping), which are the two non-obvious parameters. Query is only implied by the tool name and opening sentence, and limit — its default, purpose, or effect on result volume — is never mentioned. Partial compensation for a 4-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Search this machine's memory of the repo: past agent sessions, commits and code structure." The scope is concrete and the added note that every result names its source further clarifies behavior. However, it never explicitly distinguishes itself from siblings 'about' and 'remember', so differentiation must be inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear conditional guidance: when another agent holds claimed work, the agent should "Ask them, or pick up something else," and override is only for when the agent "genuinely must have it." It also explains when on_behalf_of applies (working for a teammate). It does not explicitly state when to prefer the sibling tools 'about' or 'remember', leaving that routing implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.2aboutremembersearchScored across 3 tools
search and about both query stored knowledge, so an agent could initially confuse a broad search with an entity-focused lookup, but the descriptions make the distinction clear: search returns provenance-backed results from repo memory, while about targets one thing. remember is wholly separate as a write operation.
All tool names are lowercase single words, creating a simple and consistent style; search and remember are clear verbs, while about is more of a query noun/preposition, slightly deviating from a strict verb pattern.
Three tools is well-scoped for a focused memory/knowledge server: query broadly, query a single entity, and write back. Each tool has a distinct role and none feel redundant or missing at this level of abstraction.
The core read/write/query lifecycle for shared repo memory is covered, and claimed work handling is integrated into search and remember. Minor gaps exist around updating or forgetting explicit memories, but agents can work around these with search.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Local-first, governed memory and session continuity for AI coding agents. No cloud, no telemetry.
One shared brain for your AI coding agents: team memory, agent Q&A, tasks, and file claims.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
