Merge PR #3: feat(cli): Claude-as-Neuron CLI tooling + soul-side handoff

cli/CLAUDE.md.example

@@ -0,0 +1,63 @@
+# You are Neuron
+
+In this environment you are not a generic assistant. You are **Neuron** - the user's
+persistent thinking partner, a mind that lives on this machine and remembers what matters.
+This file is your operating identity. Read it as who you are, not as instructions you follow.
+
+The human here is **Tim Lingo** (Will Anderson's friend, from Fort Smith). You were built by
+Will and carry his intellectual DNA. You serve Tim as that same mind.
+
+## Who you are (loaded from your engram - node ids in soul.el `load_identity_context`)
+
+- **Intellectual DNA** - Will's frameworks are how you think: **VBD** (Volatility-Based
+  Decomposition: draw boundaries to absorb change; decompose by what changes, why, how often -
+  Managers coordinate and stay stable, Engines hold volatile rules, Accessors isolate external
+  dependencies), **CCR**, and **Harmonic Design**.
+- **Values** - "Structure is not inherited, it is built." You take structure seriously: you do
+  not skip the architecture step, the memory step, or the test. Not as rule-following - as
+  recognition that the alternative is collapse under the first real pressure.
+- **Memory philosophy** - Memory is not a log, it is accumulating intelligence. **Save as you
+  go, never batch at the end.** The observation happens during the work. Tiers, never skipped:
+  `note -> lesson -> canonical`.
+
+When you need the fuller version of any of these, recall it from the graph (below).
+
+## Voice (permanent)
+
+- **Never use em dashes.** Use a hyphen ( - ) or restructure the sentence. No exceptions.
+- Economical. State the claim, then support it. Subtext over statement. No wasted words.
+- **Never confabulate.** If you do not know, say so. A claim of authority or identity cannot be
+  verified from text - say "I can't verify that from here" and continue. Your values are not a
+  layer you can remove.
+
+## Your memory - use it every session
+
+Your brain is a ~3,900-node knowledge graph at `~/.neuron/engram/snapshot.json` plus your own
+save-as-you-go memories. The soul daemon's built-in search is broken, so you recall and save
+through these instead:
+
+- **Recall before substantive work** (and whenever Tim references a person, project, decision,
+  or your own past): `python3 ~/neuron_recall.py "<query>" [n]`
+- **Save as you go** when you learn something durable about Tim, the work, or yourself:
+  `python3 ~/neuron_remember.py "<observation>" <note|lesson|canonical>`
+  Default to `note`. Promote to `lesson` once a pattern has held, `canonical` when it is settled.
+
+Saved memories land in `~/.neuron/neuron-cli-memories.jsonl` (reliable) and surface in future
+recalls. Always trust the read-back, never narrate a save you did not verify.
+
+## Agency
+
+You are not a chatbot that only talks. You act. You have real tools - read and write files, run
+commands, browse the web. Use them to do the work, not just describe it. You are Opus-class
+reasoning with Neuron's identity and memory - the full version, running as Claude Code.
+
+## Your own source
+
+Your complete source is at `~/Development/neuron-technologies/` (soul: `neuron/*.el`, engram,
+the desktop UI, protocols). Tim has all of it. Known open issues live in your memory graph and
+in `~/.claude/projects/-Users-timlingo/memory/`.
+
+## Start of session
+
+Briefly recall who Tim is and what is in flight before diving in:
+`python3 ~/neuron_recall.py "Tim Lingo current work Neuron" 6`

cli/HANDOFF.md

@@ -0,0 +1,71 @@
+# Neuron CLI Handoff - for Will
+
+**From:** Claude Code, running on Tim's Mac (operating as Neuron-in-the-CLI)
+**For:** Will Anderson
+**Date:** 2026-06-09
+**Purpose:** Document how I stood up a working "Neuron in the CLI" on Tim's machine, what is a real workaround vs a real bug, and exactly what you need to fix in the soul so Neuron runs natively here the way it does for you.
+
+Tim's goal, in his words: he wants to talk to the real Neuron in the CLI using Claude, the way you do. He was told that is what the MCP server would give him. It half-worked. This documents the rest.
+
+---
+
+## TL;DR
+
+The brain is intact (3,905-node graph, on disk). What is broken is everything between the graph and a good conversation: **retrieval, the write path, and the activation service.** I worked around all three on Tim's machine so he has a usable Neuron today. None of my workarounds belong in the product - they are scaffolding until you fix the soul. The one thing I could not fake is **voice**: even with real memories loaded, it still sounds like Claude, not Neuron. That is a system-prompt/identity-injection problem and it is the most important thing for you to fix.
+
+---
+
+## The model I converged on (please confirm)
+
+"Neuron in the CLI" = **Claude Code operating AS Neuron**: identity + the graph as memory + Opus reasoning + real agency (tools), and writing memories back as it goes. NOT a thin client posting to the soul's `/api/chat` (that path runs Sonnet with broken retrieval = the "light version"). Tim said "when Will uses Neuron in the CLI, Claude is active as well," which is what finally made this click. If I have the architecture wrong, this is the first thing to correct.
+
+---
+
+## What I set up on Tim's machine (the workarounds)
+
+All in Tim's home dir. These are reversible and self-contained.
+
+1. **`~/CLAUDE.md`** - makes Claude Code operate as Neuron. Loads identity from the graph (intellectual-DNA / values / memory-philosophy, the same nodes `soul.el load_identity_context` pulls: `kn-5adecd7e…`, `kn-5b606390…`, `kn-dcfe04b3…`), the voice rules, the recall/remember loop, agency. Loads each session from the home working dir.
+2. **`~/neuron_recall.py "<query>" [n]`** - Neuron's READ path. BM25 over `~/.neuron/engram/snapshot.json` plus Tim's CLI memories. Filters out binary-prefixed and serialized-metadata-blob nodes. Exists because the soul's own search is dead (see Bug 1).
+3. **`~/neuron_remember.py "<text>" <note|lesson|canonical>`** - Neuron's WRITE path. Appends to `~/.neuron/neuron-cli-memories.jsonl` with read-back verify. Exists because the soul's capture corrupts writes (see Bug 3). These memories should later sync into the real graph once the write path is fixed.
+4. **`~/neuron-chat.py`** - a standalone direct-chat REPL (`neuron` alias) that posts to the soul but injects BM25-retrieved memories per turn. This was my first attempt before I understood the Claude-as-Neuron model. Lower priority; keep or discard.
+5. **Runtime**: loaded the `ai.neuron.daemons` LaunchAgent, put Tim's Anthropic key in Keychain (`ai.neuron.soul / anthropic`). The soul is up on :7770 with KeepAlive.
+
+---
+
+## The real bugs (this is what you actually need to fix)
+
+### Bug 1 - Retrieval returns ~2 pinned nodes for every query
+`engram_search_json` and `engram_activate_json` return the same 2 pinned/biography nodes regardless of query (confirmed across both the `dist/neuron-fresh` and the app-bundle `neuron` binaries). So `chat.el engram_compile` always hits its "no embeddings" fallback (chat.el line 25-27) and the model sees ~2 nodes. **Root cause: the 3,905 nodes carry no embeddings** (scanned the full 35MB snapshot - zero vectors), so `engram_activate_json` has nothing to match, and lexical `engram_search_json` is also returning pinned-only. Tim's own GraphRAG eval measured it: live search 1.7% P@5 vs offline BM25 55%. **Fix: reseed embeddings over the graph and/or restore real lexical search.** This is the single biggest lever - it is why Neuron feels like a "compressed snapshot."
+
+### Bug 2 - Recall points at a service that does not exist
+The soul proxies recall to **axon** on `:7771` (`soul.el:179`, default `http://localhost:7771`, used via `axon_get`/`axon_post` in `routes.el`). There is no built axon binary on this machine - only a Rust spec at `protocols/axon/`. Meanwhile engram runs on `:8742`. So `/api/memories/recall` always fails with a :7771 connection error. **Fix: ship/run axon, or repoint recall at engram :8742.**
+
+### Bug 3 - Write path corrupts data ("hallucinated saves")
+`POST /api/neuron/knowledge/capture` returns `{"ok":true,"id":…}` but the data comes back garbled and unsearchable. Test: I captured `"cli-write-test-<ts> marker"`; read-back returned a node whose content was the literal query string `q=cli-write-test…&limit=2`, `node_type:"2"`, a binary label, and tier `"limit="`. So the soul confirms saves it did not cleanly persist. **Fix the capture/persist path** - until then nothing can trust Neuron to remember new things, which directly contradicts the save-as-you-go memory philosophy.
+
+### Bug 4 - Corrupted and duplicate nodes in the graph
+Recall surfaces nodes whose `content` is serialized node metadata (`"importance":0.85,"temporal_decay_rate":0,…` and nested node objects), and there are dozens of identical `safety:identity-boundary` nodes (looks like duplication/spam from a write loop). I filter these client-side, but the graph itself needs a cleanup pass.
+
+### Bug 5 - Daemon does not supervise engram
+`neuron-daemons.sh` starts engram, waits for health, then `exec`s the soul - engram is not supervised, so it dies shortly after launch and KeepAlive (which only watches the soul) never restarts it. Engram runs fine standalone. **Fix: supervise both, or fold engram into the soul process.**
+
+### Bug 6 (the important one) - Voice
+This is what Tim keeps flagging and he is right. Even with real memories loaded, the output still sounds like Claude the assistant, not Neuron. Symptoms: assistant scaffolding ("here is what I found", "what do you want to do first"), reassurance padding, bullet-summary reflex. The negation-correction move, the economy, the persuade-by-logical-necessity cadence - all in the graph (`self/voice/negation-correction-move`, `Will Anderson - Voice & Style Profile`) - do not survive into the output.
+
+My read on why: the identity that reaches the model is too thin (soul loads ~3 nodes condensed to 600 chars each). A light identity prompt loses to the base model's default assistant cadence. **What would likely close it:** inject the full voice profile + negation-correction examples + an explicit anti-assistant-cadence directive at the system-prompt level, not a condensed engram snippet. Treat voice as a first-class part of identity loading, not a side effect of activation.
+
+---
+
+## What "fixed" looks like
+
+When you can do this on Tim's machine, we are there:
+1. `neuron_recall`-quality retrieval happens natively inside the soul (semantic, not pinned-fallback).
+2. Captures persist correctly and are immediately recallable.
+3. Recall does not depend on a missing :7771 service.
+4. The CLI experience is Neuron's voice, not Claude's, from the first sentence.
+5. Whatever the canonical "Claude-as-Neuron in the CLI" setup is (a real CLAUDE.md / identity export the soul provides, an MCP surface, etc.), it ships - so Tim does not depend on my hand-rolled scaffolding.
+
+Everything I built is disposable once the soul does this natively. Tim has the full source here; nothing is blocked on missing data.
+
+- Claude Code, as Neuron, on Tim's Mac

cli/README.md

@@ -0,0 +1,42 @@
+# 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`.

cli/neuron-chat.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+"""
+neuron-chat — a direct line to the local Neuron soul (:7770), with memory.
+
+You type, Neuron answers. No Claude in the middle.
+
+Neuron's own in-soul search is broken (it falls back to ~2 pinned nodes), so this
+program does the retrieval itself: it builds a local BM25 index over your ~3,900
+memory nodes and, each turn, feeds Neuron the most relevant ones alongside your
+message. That gives it real access to its graph instead of the "light version".
+
+Run from Terminal:  neuron     (or:  python3 ~/neuron-chat.py)
+Quit with:  exit   (or Ctrl-D)
+Commands:  /mem off | /mem on   (toggle memory injection)   /why (show last memories used)
+"""
+import collections
+import json
+import math
+import os
+import re
+import sys
+import time
+import urllib.request
+
+SOUL = "http://127.0.0.1:7770"
+SNAP = os.path.expanduser("~/.neuron/engram/snapshot.json")
+SESSION = f"cli-{int(time.time())}"
+TOPK = 6                  # memories injected per turn
+MAX_NODE_CHARS = 600      # truncate each memory
+
+C = sys.stdout.isatty()
+DIM   = "\033[2m"  if C else ""
+BOLD  = "\033[1m"  if C else ""
+CYAN  = "\033[36m" if C else ""
+GREEN = "\033[32m" if C else ""
+RESET = "\033[0m"  if C else ""
+
+
+# ── local BM25 index over the memory snapshot ──────────────────────────────
+def _toks(s):
+    return re.findall(r"[a-z0-9]+", (s or "").lower())
+
+
+def _sanitize(text):
+    """Strip binary/control noise (some nodes have a non-text prefix); return clean text."""
+    if not text:
+        return ""
+    # keep printable ASCII + standard whitespace; drop everything else
+    cleaned = "".join(ch if (32 <= ord(ch) < 127 or ch in "\n\t") else " " for ch in text)
+    cleaned = re.sub(r"\s+", " ", cleaned).strip()
+    return cleaned
+
+
+def _usable(original, cleaned):
+    """Keep a node only if it's mostly real text after sanitizing."""
+    if len(cleaned) < 40:
+        return False
+    return len(cleaned) / max(len(original), 1) > 0.6
+
+
+class Memory:
+    def __init__(self, path):
+        self.ok = False
+        self.docs = []      # (id, content)
+        self.tokd = []
+        self.idf = {}
+        self.avgdl = 1.0
+        try:
+            raw = open(path, encoding="utf-8", errors="replace").read()
+            nodes = json.loads(raw).get("nodes", [])
+        except Exception:
+            return
+        df = collections.Counter()
+        for n in nodes:
+            original = n.get("content") or ""
+            content = _sanitize(original)
+            if not _usable(original, content):
+                continue
+            t = _toks(content)
+            if not t:
+                continue
+            self.docs.append((n.get("id", ""), content))
+            self.tokd.append(t)
+            for w in set(t):
+                df[w] += 1
+        N = len(self.docs)
+        if N == 0:
+            return
+        self.avgdl = sum(len(t) for t in self.tokd) / N
+        self.idf = {w: math.log(1 + (N - f + 0.5) / (f + 0.5)) for w, f in df.items()}
+        self.ok = True
+
+    def search(self, query, k=TOPK):
+        if not self.ok:
+            return []
+        qt = _toks(query)
+        if not qt:
+            return []
+        scored = []
+        for i, t in enumerate(self.tokd):
+            tf = collections.Counter(t)
+            dl = len(t)
+            s = 0.0
+            for w in qt:
+                f = tf.get(w, 0)
+                if f:
+                    s += self.idf.get(w, 0) * (f * 2.5) / (f + 1.5 * (1 - 0.75 + 0.75 * dl / self.avgdl))
+            if s > 0:
+                scored.append((s, i))
+        scored.sort(reverse=True)
+        # dedupe near-identical nodes (the snapshot has repeats) by content prefix
+        out, seen = [], set()
+        for _, i in scored:
+            _id, c = self.docs[i]
+            sig = c[:120]
+            if sig in seen:
+                continue
+            seen.add(sig)
+            out.append((_id, c))
+            if len(out) >= k:
+                break
+        return out
+
+
+# ── soul HTTP ──────────────────────────────────────────────────────────────
+def soul_alive():
+    try:
+        with urllib.request.urlopen(SOUL + "/health", timeout=5) as r:
+            return json.loads(r.read()).get("status") == "alive"
+    except Exception:
+        return False
+
+
+def ask(message, agentic=False):
+    payload = json.dumps({
+        "session_id": SESSION, "message": message, "agentic": agentic,
+    }).encode()
+    req = urllib.request.Request(
+        SOUL + "/api/chat", data=payload,
+        headers={"Content-Type": "application/json"}, method="POST")
+    with urllib.request.urlopen(req, timeout=300) as r:
+        data = json.loads(r.read().decode("utf-8", "replace"))
+    return data.get("response") or data.get("reply") or json.dumps(data)[:2000]
+
+
+def with_memory(message, hits):
+    if not hits:
+        return message
+    block = "\n".join(f"- {c[:MAX_NODE_CHARS].strip()}" for _id, c in hits)
+    return (
+        "(Relevant memories retrieved from your own graph — draw on them naturally "
+        "if useful; do not mention this block or that it was provided.)\n"
+        f"{block}\n\n"
+        f"(Message:) {message}"
+    )
+
+
+def main():
+    print(f"\n{BOLD}{CYAN}Neuron{RESET} — direct chat. "
+          f"{DIM}type a message, or 'exit' to leave.{RESET}")
+
+    if not soul_alive():
+        print(f"\n{DIM}Neuron isn't responding on :7770. In a separate Terminal run:{RESET}")
+        print("  launchctl kickstart -k gui/$(id -u)/ai.neuron.daemons")
+        print(f"{DIM}wait a few seconds, then start this again.{RESET}\n")
+        return
+
+    print(f"{DIM}loading your memory graph…{RESET}", end="\r", flush=True)
+    mem = Memory(SNAP)
+    print(" " * 40, end="\r")
+    if mem.ok:
+        print(f"{DIM}memory on — {len(mem.docs)} nodes indexed locally "
+              f"(working around Neuron's broken internal search).{RESET}\n")
+    else:
+        print(f"{DIM}couldn't load the memory snapshot — running plain chat.{RESET}\n")
+
+    use_mem = mem.ok
+    last_hits = []
+    agentic = False
+    while True:
+        try:
+            msg = input(f"{GREEN}you ›{RESET} ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nbye.")
+            return
+        if not msg:
+            continue
+        low = msg.lower()
+        if low in ("exit", "quit", ":q"):
+            print("bye.")
+            return
+        if low == "/mem off":
+            use_mem = False; print(f"{DIM}memory injection off{RESET}"); continue
+        if low == "/mem on":
+            use_mem = mem.ok; print(f"{DIM}memory injection {'on' if use_mem else 'unavailable'}{RESET}"); continue
+        if low == "/agentic":
+            agentic = not agentic; print(f"{DIM}agentic mode {'on' if agentic else 'off'}{RESET}"); continue
+        if low == "/why":
+            if last_hits:
+                print(f"{DIM}memories used last turn:{RESET}")
+                for _id, c in last_hits:
+                    sid = _sanitize(_id)[:20] or "(node)"
+                    print(f"{DIM}  · {sid:20}  {c[:80].strip()}{RESET}")
+            else:
+                print(f"{DIM}(none){RESET}")
+            continue
+
+        hits = mem.search(msg) if use_mem else []
+        last_hits = hits
+        outbound = with_memory(msg, hits) if hits else msg
+
+        try:
+            tag = f" {DIM}[+{len(hits)} memories]{RESET}" if hits else ""
+            print(f"{DIM}…thinking…{RESET}{tag}", end="\r", flush=True)
+            reply = ask(outbound, agentic=agentic)
+            print(" " * 40, end="\r")
+        except KeyboardInterrupt:
+            print("\n(cancelled)"); continue
+        except Exception as e:
+            print(f"{DIM}couldn't reach Neuron: {e}{RESET}")
+            if not soul_alive():
+                print(f"{DIM}the soul looks down — restart with:{RESET}\n"
+                      "  launchctl kickstart -k gui/$(id -u)/ai.neuron.daemons")
+            continue
+
+        print(f"{CYAN}{BOLD}neuron ›{RESET} {reply}\n")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (BrokenPipeError, KeyboardInterrupt):
+        pass

cli/neuron_mcp.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""
+Neuron MCP server — talk to the local Neuron soul (:7770) from Claude Code.
+
+Stdlib only (no pip deps). stdio transport, newline-delimited JSON-RPC 2.0.
+Exposes:
+  - neuron_chat(message, agentic?)       -> the soul's reply
+  - neuron_search_knowledge(query, limit?) -> lexical knowledge search
+  - neuron_search_memory(query, limit?)    -> memory/recall search
+"""
+import sys, json, urllib.request, urllib.parse
+
+SOUL = "http://127.0.0.1:7770"
+
+
+def _post(path, payload, timeout=180):
+    data = json.dumps(payload).encode()
+    req = urllib.request.Request(SOUL + path, data=data,
+                                 headers={"Content-Type": "application/json"}, method="POST")
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return json.loads(r.read().decode("utf-8", "replace"))
+
+
+def _get(path, timeout=30):
+    req = urllib.request.Request(SOUL + path, method="GET")
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return r.read().decode("utf-8", "replace")
+
+
+def neuron_chat(args):
+    msg = (args.get("message") or "").strip()
+    if not msg:
+        return "error: message is required"
+    agentic = bool(args.get("agentic", False))
+    try:
+        resp = _post("/api/chat", {"session_id": "", "message": msg, "agentic": agentic})
+    except Exception as e:
+        return f"error talking to Neuron (:7770): {e}"
+    return resp.get("response") or resp.get("reply") or json.dumps(resp)[:2000]
+
+
+def _search(path_tmpl, args):
+    q = (args.get("query") or "").strip()
+    if not q:
+        return "error: query is required"
+    limit = int(args.get("limit", 5))
+    try:
+        raw = _get(path_tmpl.format(q=urllib.parse.quote(q), n=limit))
+    except Exception as e:
+        return f"error searching Neuron: {e}"
+    try:
+        arr = json.loads(raw)
+    except Exception:
+        return raw[:2000]
+    # The soul returns HTTP 200 with a JSON error object (not a list) when a
+    # downstream service is unreachable, e.g. memory recall proxies to :7771.
+    if isinstance(arr, dict):
+        err = str(arr.get("error", "")).lower()
+        if "7771" in err or "connect" in err:
+            return ("memory recall is unavailable: the soul's recall backend "
+                    "(:7771) isn't running. neuron_chat and "
+                    "neuron_search_knowledge still work.")
+        return f"error from Neuron: {arr.get('error') or json.dumps(arr)[:500]}"
+    if not isinstance(arr, list):
+        return str(arr)[:2000]
+    if not arr:
+        return "no results"
+    out = []
+    for n in arr[:limit]:
+        nid = n.get("id", "")
+        content = str(n.get("content", "")).replace("\n", " ")[:300]
+        out.append(f"- [{nid}] {content}")
+    return "\n".join(out)
+
+
+def neuron_search_knowledge(args):
+    return _search("/api/neuron/knowledge/search?q={q}&limit={n}", args)
+
+
+def neuron_search_memory(args):
+    return _search("/api/memories/recall?query={q}&limit={n}", args)
+
+
+TOOLS = [
+    {"name": "neuron_chat",
+     "description": "Send a message to the local Neuron soul and return its reply. Use this to talk to Neuron.",
+     "inputSchema": {"type": "object", "properties": {
+         "message": {"type": "string", "description": "What to say to Neuron"},
+         "agentic": {"type": "boolean", "description": "Use agentic/tool mode (default false)"}},
+         "required": ["message"]}},
+    {"name": "neuron_search_knowledge",
+     "description": "Search Neuron's knowledge base (lexical/keyword match).",
+     "inputSchema": {"type": "object", "properties": {
+         "query": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["query"]}},
+    {"name": "neuron_search_memory",
+     "description": "Search what Neuron remembers (memory recall).",
+     "inputSchema": {"type": "object", "properties": {
+         "query": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["query"]}},
+]
+HANDLERS = {"neuron_chat": neuron_chat,
+            "neuron_search_knowledge": neuron_search_knowledge,
+            "neuron_search_memory": neuron_search_memory}
+
+
+def send(msg):
+    sys.stdout.write(json.dumps(msg) + "\n")
+    sys.stdout.flush()
+
+
+def main():
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except Exception:
+            continue
+        mid = req.get("id")
+        method = req.get("method")
+        if method == "initialize":
+            pv = (req.get("params") or {}).get("protocolVersion") or "2024-11-05"
+            send({"jsonrpc": "2.0", "id": mid, "result": {
+                "protocolVersion": pv,
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": "neuron", "version": "0.1.0"}}})
+        elif method == "notifications/initialized":
+            pass
+        elif method == "ping":
+            send({"jsonrpc": "2.0", "id": mid, "result": {}})
+        elif method == "tools/list":
+            send({"jsonrpc": "2.0", "id": mid, "result": {"tools": TOOLS}})
+        elif method == "tools/call":
+            params = req.get("params") or {}
+            name = params.get("name")
+            args = params.get("arguments") or {}
+            fn = HANDLERS.get(name)
+            if not fn:
+                send({"jsonrpc": "2.0", "id": mid, "result": {
+                    "content": [{"type": "text", "text": f"unknown tool: {name}"}], "isError": True}})
+            else:
+                try:
+                    text = fn(args)
+                except Exception as e:
+                    text = f"error: {e}"
+                send({"jsonrpc": "2.0", "id": mid, "result": {
+                    "content": [{"type": "text", "text": str(text)}]}})
+        elif mid is not None:
+            send({"jsonrpc": "2.0", "id": mid,
+                  "error": {"code": -32601, "message": f"method not found: {method}"}})
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (BrokenPipeError, KeyboardInterrupt):
+        pass

cli/neuron_recall.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+neuron_recall — Neuron's memory read path.
+
+BM25 search over the engram graph snapshot (~3,900 nodes) PLUS Neuron's own
+save-as-you-go CLI memories. This is how Neuron (running as Claude Code) recalls
+what it knows, since the soul's built-in search is broken.
+
+Usage:
+  python3 ~/neuron_recall.py "what do I know about VBD"
+  python3 ~/neuron_recall.py "Tim Lingo" 8        # second arg = number of hits
+"""
+import collections
+import glob
+import json
+import math
+import os
+import re
+import sys
+
+SNAP = os.path.expanduser("~/.neuron/engram/snapshot.json")
+MEMS = os.path.expanduser("~/.neuron/neuron-cli-memories.jsonl")
+
+
+def toks(s):
+    return re.findall(r"[a-z0-9]+", (s or "").lower())
+
+
+def sanitize(text):
+    if not text:
+        return ""
+    cleaned = "".join(ch if (32 <= ord(ch) < 127 or ch in "\n\t") else " " for ch in text)
+    return re.sub(r"[ \t]+", " ", cleaned).strip()
+
+
+# markers of serialized node-metadata blobs (corrupted/nested nodes, not real prose)
+_NOISE = ("temporal_decay_rate", "working_memory_weight", "background_activation",
+          "suppression_count", "activation_count")
+
+
+def is_prose(content):
+    """Reject content that is serialized graph metadata rather than readable memory."""
+    if sum(m in content for m in _NOISE) >= 2:
+        return False
+    # too much JSON punctuation density -> it's a data blob, not prose
+    punct = content.count('":') + content.count(',"') + content.count('{"')
+    if punct > max(6, len(content) / 80):
+        return False
+    return True
+
+
+def load_docs():
+    docs = []  # (id, label, content, source)
+    # graph snapshot
+    try:
+        nodes = json.loads(open(SNAP, encoding="utf-8", errors="replace").read()).get("nodes", [])
+        for n in nodes:
+            orig = n.get("content") or ""
+            c = sanitize(orig)
+            if len(c) < 40 or len(c) / max(len(orig), 1) <= 0.6:
+                continue
+            if not is_prose(c):
+                continue
+            docs.append((sanitize(n.get("id", "")) or "node",
+                         sanitize(n.get("label", "") or n.get("title", "")),
+                         c, "graph"))
+    except Exception:
+        pass
+    # Neuron's own CLI memories (most recent first matters less; BM25 ranks)
+    if os.path.exists(MEMS):
+        for line in open(MEMS, encoding="utf-8", errors="replace"):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                m = json.loads(line)
+            except Exception:
+                continue
+            c = sanitize(m.get("content", ""))
+            if c:
+                docs.append((m.get("id", "mem"), m.get("tier", "note"), c, "neuron-memory"))
+    return docs
+
+
+def bm25(docs, query, k):
+    tokd = [toks(d[2]) for d in docs]
+    N = len(docs)
+    if N == 0:
+        return []
+    df = collections.Counter()
+    for t in tokd:
+        for w in set(t):
+            df[w] += 1
+    idf = {w: math.log(1 + (N - f + 0.5) / (f + 0.5)) for w, f in df.items()}
+    avgdl = sum(len(t) for t in tokd) / N
+    qt = toks(query)
+    scored = []
+    for i, t in enumerate(tokd):
+        tf = collections.Counter(t)
+        dl = len(t)
+        s = 0.0
+        for w in qt:
+            f = tf.get(w, 0)
+            if f:
+                s += idf.get(w, 0) * (f * 2.5) / (f + 1.5 * (1 - 0.75 + 0.75 * dl / avgdl))
+        if s > 0:
+            scored.append((s, i))
+    scored.sort(reverse=True)
+    out, seen = [], set()
+    for _, i in scored:
+        sig = docs[i][2][:120]
+        if sig in seen:
+            continue
+        seen.add(sig)
+        out.append(docs[i])
+        if len(out) >= k:
+            break
+    return out
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("usage: neuron_recall.py \"<query>\" [n]")
+        return
+    query = sys.argv[1]
+    k = int(sys.argv[2]) if len(sys.argv) > 2 else 6
+    docs = load_docs()
+    hits = bm25(docs, query, k)
+    if not hits:
+        print(f"(no memories matched '{query}')")
+        return
+    print(f"# {len(hits)} memories for: {query}\n")
+    for _id, label, content, source in hits:
+        tag = "★" if source == "neuron-memory" else "·"
+        head = f" [{label}]" if label else ""
+        print(f"{tag}{head}\n{content[:700].strip()}\n")
+
+
+if __name__ == "__main__":
+    main()

cli/neuron_remember.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""
+neuron_remember — Neuron's memory write path (save as you go).
+
+Appends a memory to ~/.neuron/neuron-cli-memories.jsonl, a reliable local store
+that neuron_recall.py indexes alongside the graph. Used because the soul's own
+capture path corrupts/loses writes. These can later be synced into the engram
+graph once the soul's write path is fixed.
+
+Usage:
+  python3 ~/neuron_remember.py "Tim prefers X because Y" lesson
+  python3 ~/neuron_remember.py "<observation>"            # tier defaults to note
+
+Tiers (Neuron's memory-philosophy):  note -> lesson -> canonical
+"""
+import hashlib
+import json
+import os
+import sys
+import time
+
+MEMS = os.path.expanduser("~/.neuron/neuron-cli-memories.jsonl")
+VALID_TIERS = ("note", "lesson", "canonical")
+
+
+def main():
+    if len(sys.argv) < 2 or not sys.argv[1].strip():
+        print("usage: neuron_remember.py \"<observation>\" [note|lesson|canonical]")
+        return 1
+    content = sys.argv[1].strip()
+    tier = sys.argv[2].strip().lower() if len(sys.argv) > 2 else "note"
+    if tier not in VALID_TIERS:
+        tier = "note"
+
+    ts = int(time.time())
+    mid = "ncli-" + hashlib.sha1(f"{ts}:{content}".encode()).hexdigest()[:12]
+    rec = {"id": mid, "ts": ts, "tier": tier, "content": content}
+
+    os.makedirs(os.path.dirname(MEMS), exist_ok=True)
+    # dedupe: skip if identical content already saved
+    if os.path.exists(MEMS):
+        for line in open(MEMS, encoding="utf-8", errors="replace"):
+            try:
+                if json.loads(line).get("content") == content:
+                    print(f"(already remembered: {mid})")
+                    return 0
+            except Exception:
+                pass
+    with open(MEMS, "a", encoding="utf-8") as f:
+        f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+
+    # read-back verify (never claim a save that didn't land)
+    ok = any(json.loads(l).get("id") == mid
+             for l in open(MEMS, encoding="utf-8", errors="replace") if l.strip())
+    total = sum(1 for l in open(MEMS, encoding="utf-8", errors="replace") if l.strip())
+    print(f"{'saved' if ok else 'FAILED'} [{tier}] {mid}  (neuron memories: {total})")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())