Metadata-Version: 2.4
Name: nodalkb
Version: 1.0.0
Summary: Nodal — local-first personal memory layer for AI agents: markdown vault + hybrid retrieval, exposed over MCP.
License: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]>=1.27.1
Requires-Dist: python-ulid>=3.1.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: fastembed>=0.4.0
Requires-Dist: numpy>=2.4.6
Requires-Dist: textual>=3.0
Requires-Dist: langsmith>=0.1.0
Provides-Extra: ann
Requires-Dist: hnswlib>=0.8.0; extra == "ann"
Provides-Extra: trace

<p align="center">
  <img alt="Nodal" src="https://engram-site-xi.vercel.app/icon.png" width="120" height="120">
</p>

<p align="center"><strong>A local-first shared brain for AI agents.</strong><br>
One markdown file per fact, on your disk — written and recalled by every agent
on your machine over MCP, and by you with <code>grep</code>.</p>

<p align="center">
  <a href="https://pypi.org/project/nodalkb/"><img alt="PyPI" src="https://img.shields.io/pypi/v/nodalkb?style=flat-square&color=177a44&label=pypi"></a>
  <a href="https://pypi.org/project/nodalkb/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/nodalkb?style=flat-square&color=14171b"></a>
  <img alt="MCP tools" src="https://img.shields.io/badge/MCP-44_tools-6fdd8b?style=flat-square&labelColor=14171b">
  <a href="https://github.com/arjan-experiments/kb/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-14171b?style=flat-square"></a>
</p>

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

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

Or do it by hand:

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

```json
{ "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):

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