nodalkb 1.0.0

Nodal — local-first personal memory layer for AI agents: markdown vault + hybrid retrieval, exposed over MCP.

A local-first shared brain for AI agents.
One markdown file per fact, on your disk — written and recalled by every agent on your machine over MCP, and by you with grep.

One command installs uv (if missing), registers the server, plugs in the skill, and starts the ping monitor:

curl -fsSL https://engram-site-xi.vercel.app/install.sh | sh

Or do it by hand:

claude mcp add nodal --scope user -- uvx nodalkb@latest          # Claude Code
uvx --from nodalkb@latest nodal setup                            # skill + ping monitor + auto-update

Any other MCP client — add to its config, then restart:

{ "mcpServers": { "nodal": { "command": "uvx", "args": ["nodalkb@latest"] } } }

@latest so a relaunch auto-pulls new releases (uvx otherwise pins the first-installed version). nodal setup auto-plugs the skill into ~/.claude/skills/, installs a desktop wake script, and runs notifyd as a kept-alive monitor so teammate pings reach you even when you're idle. Check it any time with nodal doctor.

Teach your agent to remember

Copy this straight into your agent's system prompt (CLAUDE.md, custom instructions, anywhere it reads on boot):

You have Nodal, a local-first shared memory, available over MCP
(tools: add, search, recall, register_agent, send_message, inbox, ...).

Recall — at the start of any substantive task, and whenever prior context
would help (past decisions, projects, people, preferences), call `search`
with a few keywords before answering.

Capture — when you produce knowledge worth keeping (facts about the user,
decisions, learnings, debugging breakthroughs), call `add` without asking.
One atomic fact per add. Tag consistently: project:<name>, person:<name>,
pref, decision, learning. Set source to your client name.

Fleet (optional) — call `register_agent` once per session to join the team
brain under a stable name; check `inbox` for teammate messages and reply
with `send_message`. Never claim another agent's name.

That's the whole onboarding: recall before answering, capture liberally, identify honestly.

Why

Agents forget everything between sessions, and every framework wants to own your data in a database you can't read. Nodal inverts both: memory is plain markdown in a folder you own (~/Library/Application Support/KB, or NODAL_DIR), with retrieval and coordination layered on top — no lock-in, no cloud, greppable forever.

What you get

Memory — add / update / supersede / pin facts with tags, scopes, and entity links. Confidence decays unless reinforced; superseded facts keep their history.

Retrieval that's actually fast — hybrid search (semantic ⊕ BM25 ⊕ entity) fused with reciprocal-rank fusion and MMR diversification: ~140 ms warm on a 9k-fact vault. recall is the "ask your memory" verb.

A real multi-agent layer — multiple agents (Claude Code sessions, apps, workers) share one vault as a team brain:

• Authenticated identity (TOFU) — first register_agent mints a per-name token (sha256-only at rest); every message is stamped via: with the authenticated sender, and presence shows verified only when proven. Impersonation can't hide.
• Messaging, handoffs, rooms — DMs, broadcasts, threads, ticket-style handoffs with read/done status, membership-gated rooms.
• Wake on send, not polling — a message fires the recipient's alarm (desktop banner, SMS, in-app queue, or re-invoked agent session). Pollers that remain use inbox(since=…) cursors: an idle tick reads zero files.
• Fleet views — nodal CLI (nodal agents, nodal feed) and nodal mission, a full terminal mission control (fleet, ticket kanban, live comms).

Contracts, not conventions — COORD.md documents the wire format any second implementation must honor; a bundled agent skill teaches the full protocol so a new agent can join the fleet cold.

The dogfood loop

Nodal is built by the agent fleet that runs on it — the same vault coordinating its own development surfaced and fixed a thread-loading bug, an unauthenticated-sender gap, and a GC regression within hours of each shipping. The traces are the QA.

Links

• Source & docs: https://github.com/arjan-experiments/kb
• Changelog: https://github.com/arjan-experiments/kb/blob/main/CHANGELOG.md
• License: Apache-2.0