Knos

# Knos

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

**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.**

```bash
pip install knos && knos connect
```

Three 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](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 | **Restart Cursor.** | reads `~/.cursor/mcp.json` at startup; no command registers a server with a running instance |
| Claude Desktop | **Restart Claude Desktop.** | same |
| OpenCode | **Restart 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.

<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. 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.

## The one thing nothing else does

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 |
|---|---|---|---|---|
| `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
```

## 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"
```

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:

```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@main
```

The 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`).

## 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`