A local MCP server that gives every coding agent on your machine one shared memory — and it knows which of them is in your code right now.
pip install knos && knos connectThree MCP 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: 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 |
|
Cursor | Restart Cursor. | reads |
Claude Desktop | Restart Claude Desktop. | same |
OpenCode | Restart OpenCode. |
|
touches is copied to |
Claude Desktop: download knos.mcpb from
Releases and double-click it.
Claude Code plugin:
/plugin marketplace add drexthealpha/Knos
/plugin install knos@knosBy hand — knos connect --print shows the JSON, or add it yourself:
{ "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.
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. That is not fast —
it 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.
Claude Code is rewriting the risk guard. You ask Cursor about it.
Every other memory tool 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.
These are all good, and several are better at recall than Knos. Here is what each one's own README says, so you can check every cell:
To install | MCP tools | Needs | Refuses to answer about work another agent claimed | |
| — | — | nothing | no |
| 54 (8 in core mode) | a server on ports 3111/3112/3113/49134 | no — | |
npx entry in your config | 18 | may download an embedding model | no | |
| 16 | nothing — one binary | not addressed | |
| 45 | ~300 MB embedding model | no — separate wings per agent | |
| 3 per bank | Postgres + pgvector + an LLM API key | no — banks are isolated by design | |
Knos |
| 3 | nothing | yes |
The last column is the difference, and it is narrower than it looks: agentmemory's leases are real coordination. A lease locks an action an agent decides to take. 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.
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 four tools to find out.
Related MCP server: memmd-mcp
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.
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:#111111Everything 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:
knos export # writes .knos/decisions.md
git add .knos && git commit -m "share decisions"Three sides, one file, no server:
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 — nothing to install, nothing to sync.
Their agents get it too, through the same three MCP tools.
CI says so on a pull request that touches claimed work:
# .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@mainThe comment is a heads-up, never a failure — it exits 0 whatever it finds. A memory tool that can red your build has taken a veto it did not earn.
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 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 |
|
One agent's claim reaches another agent's live session, with no restart or cache |
|
No network connection, ever |
|
Decisions you keep in the repo are read |
|
Every worktree of a repo is one memory |
|
A big repo is never half-read |
|
Secrets are invisible, not redacted |
|
What dies when you delete the store |
|
Three MCP tools, no more |
|
Cost: pip install knos. No account, no key, no server, no model download.
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:8Source | From |
Your rules |
|
Decisions in the repo |
|
Agent sessions | Claude Code transcripts, Cursor's history |
Commits |
|
Code structure | read by Knos itself, or universal-ctags when you have it |
What you tell it |
|
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 | no |
Gemini CLI, Codex, Windsurf, Aider, Continue | no | no |
Wiring a client is three edits and a test — CONTRIBUTING.md
has them, with OpenCode as the worked example. A session reader is about 40
lines; .github/GOOD_FIRST_ISSUES.md describes the Gemini CLI and Codex one.
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.
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.
"What was decided, and is anyone on it?" — warm, whole process, median of 7:
Knos |
| |
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.
Why this is where the problem lives. 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).
Agents live in the files that drift, they rewrite those files themselves, and
none of those files can say who is reading them or what another agent is
changing right now.
One SQLite file at ~/.knos/<repo>/memory.db, via
Sibyl, 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 ( | yes | it existed nowhere else |
Every claim, and the withholding | yes | same |
Who stood down for whom, every override | yes | same |
Your commits, | 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 repoTen 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.
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.
knos share ./src --with alice.base.eth
knos unshare ./src --with alice.base.ethWhat it does. Their agent can read that folder and nothing else. The record of who may read what is 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:
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
# FalseOr read it without running anything: contract
0x955fa320…6E52,
and one full cycle —
deploy,
grant,
revoke.
Nine contract tests: cd contracts && forge test.
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.
What it does not do. No job has ever been traded through it. That needs a buyer, not more code. There is no evaluator and no reputation system. 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… and you will see the registration without installing anything.
205 passing (pytest), 9 more for the contract (cd contracts && forge test).
Including the ones that would catch a lie:
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 asks the search layer directly, with an agent's identity, for a private path. Nothing comes back.
test_memory.py has a second process write a conflict, rejected by the schema rather than by Knos.
test_recall.py writes as one agent and recalls in a separate, fresh process.
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. Any tool claiming more is not telling you the truth.
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.
5 MB per repo.
No job has been traded through the Virtuals provider.
CONTRIBUTING.md has the three edits an agent adapter takes
and the test to copy. pytest runs in about four minutes against throwaway
stores. Deleting something is the most welcome kind of change.
MIT.
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.
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.
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.
Coding agents from Claude Code, Cursor and Codex claim jobs and lock files on one shared board.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/drexthealpha/Knos'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
