Tim Lingo
2ea1d50fa3
Neuron Soul CI / build (pull_request) Successful in 5m10s
Tooling built on Tim's machine to run Neuron from the terminal as a
Claude Code session (identity + graph memory + agency) instead of
relaying to the soul's /api/chat.
- cli/neuron_recall.py BM25 read over the engram snapshot + CLI memories
(works around pinned-only soul search)
- cli/neuron_remember.py reliable local memory writes with read-back verify
(works around the corrupting capture endpoint)
- cli/neuron-chat.py standalone direct-chat REPL with per-turn memory injection
- cli/neuron_mcp.py stdlib MCP server (chat/search) with graceful degradation
- cli/CLAUDE.md.example the operating identity that makes Claude Code run as Neuron
- cli/HANDOFF.md soul-side bugs to fix so this becomes unnecessary
Scaffolding/proposal - intended to be retired once the soul does native
retrieval, correct persistence, and a real CLI identity/voice surface.
Pairs with the runtime model-passthrough + UTF-8 fixes in the el repo.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
43 lines
2.4 KiB
Markdown
43 lines
2.4 KiB
Markdown
# 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`.
|