# Neuron in the CLI (Claude-as-Neuron)

Tooling for running Neuron from the terminal as a Claude Code session, rather than
relaying to the soul's `/api/chat`. Built on Tim's machine 2026-06-09. Treat this as a
proposal: it is scaffolding that works around current soul limitations, and most of it
should be retired once the soul does these things natively.

## The model

"Neuron in the CLI" = Claude Code operating **as** Neuron: the soul/graph provide identity
and memory, Claude Code provides reasoning and agency (real tools, plus writing memories
back). Posting to the soul's non-agentic `/api/chat` gives the "light version" (Sonnet,
plus the retrieval problems below), so this approach puts the reasoning in Claude Code and
reads/writes the graph directly.

## Files

- **`CLAUDE.md.example`** - the operating identity. Placed at a session's working-dir root
  (e.g. `~/CLAUDE.md`), it makes Claude Code load Neuron's identity from the graph
  (intellectual-DNA / values / memory-philosophy), hold the voice rules, and run the
  recall/remember loop. Example contains Tim-specific context; genericize before reuse.
- **`neuron_recall.py "<query>" [n]`** - READ path. BM25 over
  `~/.neuron/engram/snapshot.json` plus local CLI memories. Filters binary-prefixed and
  serialized-metadata nodes. Exists because the soul's in-process search returns ~2 pinned
  nodes for every query.
- **`neuron_remember.py "<text>" <note|lesson|canonical>`** - WRITE path. Appends to
  `~/.neuron/neuron-cli-memories.jsonl` with read-back verify. Exists because the soul's
  `/api/neuron/knowledge/capture` corrupts/loses writes. These should sync into the graph
  once the write path is fixed.
- **`neuron-chat.py`** - standalone direct-chat REPL that posts to the soul but injects
  BM25-retrieved memories per turn. Earlier approach, kept for reference.
- **`neuron_mcp.py`** - stdlib MCP server exposing `neuron_chat`, `neuron_search_knowledge`,
  `neuron_search_memory` to Claude Code, with graceful degradation when the soul's memory
  recall backend is down.
- **`HANDOFF.md`** - full writeup of what was set up and the soul-side bugs to fix
  (retrieval/embeddings, the missing axon :7771 service, the write path, daemon engram
  supervision, and voice).

## What should replace this

When the soul does native semantic retrieval, persists captures correctly, and exposes a
real identity/voice surface for the CLI, these scripts become unnecessary. See `HANDOFF.md`.