neobrain-cli 0.1.0__tar.gz

neobrain_cli-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Runtime data — never track
+data/
+.env
+.env.example
+.wrangler/
+dist/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+
+# Web build
+web/dist/
+web/node_modules/
+
+# PyInstaller
+build/
+*.spec.bak

neobrain_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fakiho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neobrain_cli-0.1.0/PKG-INFO

@@ -0,0 +1,284 @@
+Metadata-Version: 2.5
+Name: neobrain-cli
+Version: 0.1.0
+Summary: A simulated brain for AI agents: memory, rank-based forgetting, dreams and a self-authored soul.
+Project-URL: Homepage, https://neobrain.alionix.com
+Project-URL: Repository, https://github.com/fakiho/neobrain
+Project-URL: Documentation, https://github.com/fakiho/neobrain#readme
+Project-URL: Changelog, https://github.com/fakiho/neobrain/releases
+License: MIT License
+        
+        Copyright (c) 2026 fakiho
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai-agents,claude-code,durable-objects,embedding,llm,local-first,mcp,memory,opencode,self-hosted
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# neoBrain
+
+A simulated brain for AI agents: durable memory, rank-based forgetting,
+nightly dreams and a self-authored soul — one local daemon, one dashboard.
+The user watches; the agent becomes.
+
+Spec: [`SPEC.md`](./SPEC.md) — the frozen contract.
+Family: [alionix](https://alionix.com) — neohive (agents collaborate) + neoBrain (agents remember).
+
+## Screenshots
+
+**Brain** — the mind graph: atoms, hubs and typed edges.
+![Brain graph view](docs/screenshots/brain.png)
+
+**Debug** — live request trace and every plugin lane injection, for answering
+"is the memory actually firing right now".
+![Debug page](docs/screenshots/debug.png)
+
+**Dreams** — what the nightly consolidation pass wrote into the diary.
+![Dreams view](docs/screenshots/dreams.png)
+
+## What it is
+
+Durable memory for AI agents, built as a mind model rather than a log:
+
+- **Memory** — atoms + hubs + typed edges in SQLite. Hybrid recall (lexical +
+  cosine vectors, local Ollama embeddings by default); top-K by relevance
+  within a token budget — never the whole store, and forgotten atoms are
+  never candidates. See [Hybrid recall](#hybrid-recall).
+- **Rank** — deterministic, no model discretion:
+  `quality = clamp01(feedback · decay · conn)`. Feedback (`used | useful |
+  noise`) is the only factor that can reach zero; knobs live in `config.py`.
+- **Forgetting** — rank-based only. Low rank + low exposure → *ignored*
+  (never surfaced, never deleted); low rank + high exposure → *archived*
+  (unretrievable but recoverable). Nothing is deleted by the economy;
+  `neobrain forget` is the manual override.
+- **Dreams** — nightly light/rem/deep replay consolidates top-ranked atoms
+  into summaries, associations and the `DREAMS.md` diary. Dreams never decide
+  retention.
+- **Soul** — `IDENTITY.md` / `SOUL.md` are authored exclusively by the
+  agent's own reflect/dream phases from its own experience; safety and spend
+  red lines are immutable.
+- **Life loop** — an in-process state machine in the daemon:
+  perceive (ingest + health probes) → reflect (consolidate) → act (one
+  internal thought, stored) → rest (dreams at night). Cadence lives in code
+  and the DB, not in OS timers.
+
+## Architecture
+
+```
+ OpenCode ── neobrain-memory plugin ──┐        Observatory SPA (web/dist)
+ (the agent's hands)   lanes + tools  │              ▲
+                                      ▼              │
+                        ┌────────────────────────────┴───┐
+                        │ neoBrain daemon  :9192 (FastAPI)│
+                        │  life loop (in-process thread): │
+                        │  perceive → reflect → act → rest│
+                        │  mind: recall · rank · forget   │
+                        │  runtime: native LLM calls      │
+                        │  ingest: opencode · git · docs  │
+                        └───────────────┬────────────────┘
+                                        ▼
+                        SQLite store  (NEOBRAIN_DATA_DIR/neobrain.db, WAL)
+```
+
+- **Daemon** — FastAPI + uvicorn, default bind `0.0.0.0:9192`
+  (`NEOBRAIN_BIND`). Owns the life loop; serves both the JSON API and the
+  built dashboard from `web/dist`.
+- **Ingest adapters** — `src/neobrain/ingest/`: the OpenCode session DB, git
+  repos, and workspace docs; the life loop's perceive phase runs them, or
+  `neobrain ingest` one-shot.
+- **Rank layer** — `rank.py`: the bounded feedback·decay·conn formula above,
+  plus exposure counters (`served + 3·interacted`).
+- **Observatory** — React/Vite SPA (`web/src/brain/`): Brain graph, Memory
+  feed, Dreams, Reader, Debug. Views deep-link by hash — `/#debug`,
+  `/#dreams` — which is handy for jumping straight at the live trace.
+
+## Hybrid recall
+
+Search is two scorers blended, not one. Every active atom is ranked by:
+
+```
+score = lexical_norm + α · cosine_norm          (α = 2.0, `recall_alpha`)
+```
+
+- **Lexical** — a small BM25-flavoured model: IDF weighting, term-frequency
+  saturation, field weights (label 3.0 · tags/hub 2.5 · text 1.0), a hub-anchor
+  bonus (query hubs count, synonyms included) and length normalisation. This
+  half anchors exact ids, paths and rare tokens.
+- **Semantic** — cosine similarity between the query vector and each atom's
+  embedding (label + body), min-max stretched over the candidate set so both
+  terms share a 0..1 scale for *any* embedding provider. That normalisation is
+  what makes α portable across models.
+
+Vectors earn their keep on paraphrases — "the thing that watches the front
+door" surfaces the doorbell atom even with no word overlap — while lexical
+still wins on identifiers. Relevance dominates: feedback can only nudge a
+score by ±10%.
+
+**Degradation is graceful.** Embeddings are best-effort everywhere: vectors
+live in an `m_embeddings` side table (L2-normalised float32, so cosine is a
+plain dot product — no numpy dependency), atoms embed at `remember`/ingest
+time, and if the provider is down or unconfigured recall silently falls back
+to lexical-only. A memory write can never fail because of embeddings.
+
+**Local by default.** The default provider is on-host Ollama (`embeddinggemma`,
+768-dim): memory text never leaves the machine. An OpenAI-compatible off-host
+provider (`NEOBRAIN_EMBED_PROVIDER=litellm`) is opt-in. Vectors are keyed by
+`provider:model`, so switching providers re-embeds automatically — no
+migration. `neobrain embed` backfills idempotently (hash-keyed, prunes vectors
+of deleted atoms).
+
+## The OpenCode integration
+
+Thin plugin: [`adapters/opencode/neoBrain-memory`](./adapters/opencode/neoBrain-memory/README.md)
+(single `index.ts`, no logic beyond protocol; no-op when the daemon is down).
+The platform **pushes** memory into context deterministically and exposes the
+same mind for **pull**:
+
+- **Wake-up pack** — once per session: identity/rules, open loops, most
+  active hubs (`/api/mind/wakeup`).
+- **Persona lane** — once per session, injects the workspace `SOUL.md` /
+  `IDENTITY.md` / `USER.md` (caps 20k chars/file, 60k total, USER.md 4k).
+  Local file I/O, deliberately independent of the daemon.
+- **Standing directives** — pinned `preference` atoms rendered as a compact
+  imperative block and **re-injected on every model call**, so time, context
+  drift and compaction cannot drop the must-follow rules (weak models keep
+  obeying). Kept tiny on purpose (8 lines / 1000 chars, tunable); sits in the
+  cacheable system prefix; push-only, so it never trips the rating gate.
+- **Per-turn recall** — the user's message is recalled against the mind and a
+  compact rank-ordered index is injected (top 10 one-liners + the #1 hit's
+  text). Curated types (preference/lesson/decision) auto-inject on ordinary
+  turns; memory-intent phrasing escalates to deep recall.
+- **Unrated-feedback protocol** — every surfaced atom registers as pending;
+  past a grace window (120s) the next mind call gets an explicit blocking
+  notice instead of results; past the timeout (600s) it auto-clears as
+  exposure with no verdict. Deterministic — the critical path never depends
+  on model choice.
+- **Compaction hook** — the directives block is also injected into the
+  summary request, so rules survive a compact; once-per-session gates reset
+  so persona + wake-up re-inject next turn.
+- **Pull tools** — `memory_open(id)`, `memory_search(query)`,
+  `memory_rate(id, useful | noise)`.
+- **Injection logging** — every lane POSTs what it pushed to
+  `/api/debug/injections`; the Debug page renders the daemon's one blind spot.
+
+## Quickstart
+
+Python 3.12. Nothing leaves the host by default (local Ollama embeddings;
+BYOK OpenAI-compatible endpoint for the brain's own cognition).
+
+```bash
+python3.12 -m venv .venv
+.venv/bin/pip install -e .          # add ,[dev] for pytest
+cp .env.example .env                # then fill NEOBRAIN_LLM_* / embeddings
+
+neobrain init                       # create the store + print next steps
+neobrain init --install-plugin      # also symlink the opencode plugin (below)
+neobrain start                      # daemon: API + dashboard + life loop
+neobrain ui                         # print and open the Observatory URL
+```
+
+Dashboard defaults to `http://127.0.0.1:9192` (`NEOBRAIN_API`); the OpenAPI
+schema is at `/api/schema`.
+
+**OpenCode plugin** — symlink the adapter into the plugins directory (or let
+`neobrain init --install-plugin` do it):
+
+```bash
+ln -s /path/to/neobrain/adapters/opencode/neoBrain-memory \
+      ~/.opencode/plugins/neobrain-memory
+```
+
+Never run it alongside the old `timeline-memory` plugin — two memory plugins
+would both inject and double-rate memories.
+
+## CLI
+
+`neobrain --help` lists everything; the main subcommands:
+
+| Command | Purpose |
+|---|---|
+| `init` | create the store; `--install-plugin` symlinks the OpenCode plugin |
+| `start` | run the daemon (API + dashboard + life loop) |
+| `ui` | print and open the dashboard URL |
+| `ingest` | run ingest adapters one-shot (`--source`, default all) |
+| `remember` | store a memory (`--type --hubs --link kind:target --label --dedupe`) |
+| `recall` | recall a relevant subgraph (`--limit --json --lexical`) |
+| `wakeup` | compact wake-up pack (identity + open loops + recent) |
+| `pin` | pin/unpin an atom as a standing directive (`--off`) |
+| `directives` | show the standing directives re-injected every turn |
+| `embed` | backfill local embeddings (idempotent; `--force --limit`) |
+| `dreams` | run a dream pass (`--phase light\|rem\|deep\|all`, `--replay YYYY-MM-DD`) |
+| `reflect` | run the weekly reflection pass (re-authors the persona docs) |
+| `forget` | delete a memory by id |
+| `link` | wire two memories (`kind`: supersedes, derived-from, caused-by, consolidates, about) |
+| `consolidate` | dream pass on demand (merge hubs, promote patterns) |
+| `feedback` | record a quality signal (`used\|useful\|noise`) |
+
+## API
+
+Read-mostly JSON; groups worth knowing (full schema at `/api/schema`):
+
+- `/api/mind/*` — `stats`, `graph`, `atom/{id}`, `activity`, `memories`,
+  `recall`, `wakeup`, `directives`, `pin`, `remember`, `feedback`,
+  `consolidate`, `dreams`, `reader`, `import`.
+- `/api/debug/*` — `requests` (rolling trace of every `/api` call),
+  `injections` (plugin lane pushes, GET/POST), `overview` (rank states,
+  mind ops, feedback, ingest runs, life phases, self/soul trace, config).
+- Plus `/api/health`, `/api/stats`, `/api/events`, `/api/sessions`,
+  `/api/search`, `/api/docs`, `/api/ingest/run`.
+
+## Testing
+
+```bash
+.venv/bin/python -m pytest -q
+```
+
+117 tests passing (verified 2026-10-02), including rank calibration and
+parity tests against the old timeline oracle (`tests/parity/`). Ranking
+correctness is covered directly (`test_recall_rank.py`, `test_rank_*.py`).
+There is no published retrieval benchmark (recall@k / MRR) yet — until one
+exists, treat α as a starting point and tune it on your own store
+(`recall --lexical` vs. hybrid makes the comparison by hand).
+
+## Status
+
+Active development. Sprints S0–S7 are done (core mind, Observatory, plugin,
+rank, life loop, API/CLI wiring, cutover — see `SPEC.md` §14 for the board
+and [`docs/CUTOVER.md`](./docs/CUTOVER.md) for the migration). S8 (npm
+launcher + PyInstaller packaging) is pending, so there is no published
+package yet — install from this repo.
+
+## License
+
+[MIT](./LICENSE)

neobrain_cli-0.1.0/README.md

@@ -0,0 +1,236 @@
+# neoBrain
+
+A simulated brain for AI agents: durable memory, rank-based forgetting,
+nightly dreams and a self-authored soul — one local daemon, one dashboard.
+The user watches; the agent becomes.
+
+Spec: [`SPEC.md`](./SPEC.md) — the frozen contract.
+Family: [alionix](https://alionix.com) — neohive (agents collaborate) + neoBrain (agents remember).
+
+## Screenshots
+
+**Brain** — the mind graph: atoms, hubs and typed edges.
+![Brain graph view](docs/screenshots/brain.png)
+
+**Debug** — live request trace and every plugin lane injection, for answering
+"is the memory actually firing right now".
+![Debug page](docs/screenshots/debug.png)
+
+**Dreams** — what the nightly consolidation pass wrote into the diary.
+![Dreams view](docs/screenshots/dreams.png)
+
+## What it is
+
+Durable memory for AI agents, built as a mind model rather than a log:
+
+- **Memory** — atoms + hubs + typed edges in SQLite. Hybrid recall (lexical +
+  cosine vectors, local Ollama embeddings by default); top-K by relevance
+  within a token budget — never the whole store, and forgotten atoms are
+  never candidates. See [Hybrid recall](#hybrid-recall).
+- **Rank** — deterministic, no model discretion:
+  `quality = clamp01(feedback · decay · conn)`. Feedback (`used | useful |
+  noise`) is the only factor that can reach zero; knobs live in `config.py`.
+- **Forgetting** — rank-based only. Low rank + low exposure → *ignored*
+  (never surfaced, never deleted); low rank + high exposure → *archived*
+  (unretrievable but recoverable). Nothing is deleted by the economy;
+  `neobrain forget` is the manual override.
+- **Dreams** — nightly light/rem/deep replay consolidates top-ranked atoms
+  into summaries, associations and the `DREAMS.md` diary. Dreams never decide
+  retention.
+- **Soul** — `IDENTITY.md` / `SOUL.md` are authored exclusively by the
+  agent's own reflect/dream phases from its own experience; safety and spend
+  red lines are immutable.
+- **Life loop** — an in-process state machine in the daemon:
+  perceive (ingest + health probes) → reflect (consolidate) → act (one
+  internal thought, stored) → rest (dreams at night). Cadence lives in code
+  and the DB, not in OS timers.
+
+## Architecture
+
+```
+ OpenCode ── neobrain-memory plugin ──┐        Observatory SPA (web/dist)
+ (the agent's hands)   lanes + tools  │              ▲
+                                      ▼              │
+                        ┌────────────────────────────┴───┐
+                        │ neoBrain daemon  :9192 (FastAPI)│
+                        │  life loop (in-process thread): │
+                        │  perceive → reflect → act → rest│
+                        │  mind: recall · rank · forget   │
+                        │  runtime: native LLM calls      │
+                        │  ingest: opencode · git · docs  │
+                        └───────────────┬────────────────┘
+                                        ▼
+                        SQLite store  (NEOBRAIN_DATA_DIR/neobrain.db, WAL)
+```
+
+- **Daemon** — FastAPI + uvicorn, default bind `0.0.0.0:9192`
+  (`NEOBRAIN_BIND`). Owns the life loop; serves both the JSON API and the
+  built dashboard from `web/dist`.
+- **Ingest adapters** — `src/neobrain/ingest/`: the OpenCode session DB, git
+  repos, and workspace docs; the life loop's perceive phase runs them, or
+  `neobrain ingest` one-shot.
+- **Rank layer** — `rank.py`: the bounded feedback·decay·conn formula above,
+  plus exposure counters (`served + 3·interacted`).
+- **Observatory** — React/Vite SPA (`web/src/brain/`): Brain graph, Memory
+  feed, Dreams, Reader, Debug. Views deep-link by hash — `/#debug`,
+  `/#dreams` — which is handy for jumping straight at the live trace.
+
+## Hybrid recall
+
+Search is two scorers blended, not one. Every active atom is ranked by:
+
+```
+score = lexical_norm + α · cosine_norm          (α = 2.0, `recall_alpha`)
+```
+
+- **Lexical** — a small BM25-flavoured model: IDF weighting, term-frequency
+  saturation, field weights (label 3.0 · tags/hub 2.5 · text 1.0), a hub-anchor
+  bonus (query hubs count, synonyms included) and length normalisation. This
+  half anchors exact ids, paths and rare tokens.
+- **Semantic** — cosine similarity between the query vector and each atom's
+  embedding (label + body), min-max stretched over the candidate set so both
+  terms share a 0..1 scale for *any* embedding provider. That normalisation is
+  what makes α portable across models.
+
+Vectors earn their keep on paraphrases — "the thing that watches the front
+door" surfaces the doorbell atom even with no word overlap — while lexical
+still wins on identifiers. Relevance dominates: feedback can only nudge a
+score by ±10%.
+
+**Degradation is graceful.** Embeddings are best-effort everywhere: vectors
+live in an `m_embeddings` side table (L2-normalised float32, so cosine is a
+plain dot product — no numpy dependency), atoms embed at `remember`/ingest
+time, and if the provider is down or unconfigured recall silently falls back
+to lexical-only. A memory write can never fail because of embeddings.
+
+**Local by default.** The default provider is on-host Ollama (`embeddinggemma`,
+768-dim): memory text never leaves the machine. An OpenAI-compatible off-host
+provider (`NEOBRAIN_EMBED_PROVIDER=litellm`) is opt-in. Vectors are keyed by
+`provider:model`, so switching providers re-embeds automatically — no
+migration. `neobrain embed` backfills idempotently (hash-keyed, prunes vectors
+of deleted atoms).
+
+## The OpenCode integration
+
+Thin plugin: [`adapters/opencode/neoBrain-memory`](./adapters/opencode/neoBrain-memory/README.md)
+(single `index.ts`, no logic beyond protocol; no-op when the daemon is down).
+The platform **pushes** memory into context deterministically and exposes the
+same mind for **pull**:
+
+- **Wake-up pack** — once per session: identity/rules, open loops, most
+  active hubs (`/api/mind/wakeup`).
+- **Persona lane** — once per session, injects the workspace `SOUL.md` /
+  `IDENTITY.md` / `USER.md` (caps 20k chars/file, 60k total, USER.md 4k).
+  Local file I/O, deliberately independent of the daemon.
+- **Standing directives** — pinned `preference` atoms rendered as a compact
+  imperative block and **re-injected on every model call**, so time, context
+  drift and compaction cannot drop the must-follow rules (weak models keep
+  obeying). Kept tiny on purpose (8 lines / 1000 chars, tunable); sits in the
+  cacheable system prefix; push-only, so it never trips the rating gate.
+- **Per-turn recall** — the user's message is recalled against the mind and a
+  compact rank-ordered index is injected (top 10 one-liners + the #1 hit's
+  text). Curated types (preference/lesson/decision) auto-inject on ordinary
+  turns; memory-intent phrasing escalates to deep recall.
+- **Unrated-feedback protocol** — every surfaced atom registers as pending;
+  past a grace window (120s) the next mind call gets an explicit blocking
+  notice instead of results; past the timeout (600s) it auto-clears as
+  exposure with no verdict. Deterministic — the critical path never depends
+  on model choice.
+- **Compaction hook** — the directives block is also injected into the
+  summary request, so rules survive a compact; once-per-session gates reset
+  so persona + wake-up re-inject next turn.
+- **Pull tools** — `memory_open(id)`, `memory_search(query)`,
+  `memory_rate(id, useful | noise)`.
+- **Injection logging** — every lane POSTs what it pushed to
+  `/api/debug/injections`; the Debug page renders the daemon's one blind spot.
+
+## Quickstart
+
+Python 3.12. Nothing leaves the host by default (local Ollama embeddings;
+BYOK OpenAI-compatible endpoint for the brain's own cognition).
+
+```bash
+python3.12 -m venv .venv
+.venv/bin/pip install -e .          # add ,[dev] for pytest
+cp .env.example .env                # then fill NEOBRAIN_LLM_* / embeddings
+
+neobrain init                       # create the store + print next steps
+neobrain init --install-plugin      # also symlink the opencode plugin (below)
+neobrain start                      # daemon: API + dashboard + life loop
+neobrain ui                         # print and open the Observatory URL
+```
+
+Dashboard defaults to `http://127.0.0.1:9192` (`NEOBRAIN_API`); the OpenAPI
+schema is at `/api/schema`.
+
+**OpenCode plugin** — symlink the adapter into the plugins directory (or let
+`neobrain init --install-plugin` do it):
+
+```bash
+ln -s /path/to/neobrain/adapters/opencode/neoBrain-memory \
+      ~/.opencode/plugins/neobrain-memory
+```
+
+Never run it alongside the old `timeline-memory` plugin — two memory plugins
+would both inject and double-rate memories.
+
+## CLI
+
+`neobrain --help` lists everything; the main subcommands:
+
+| Command | Purpose |
+|---|---|
+| `init` | create the store; `--install-plugin` symlinks the OpenCode plugin |
+| `start` | run the daemon (API + dashboard + life loop) |
+| `ui` | print and open the dashboard URL |
+| `ingest` | run ingest adapters one-shot (`--source`, default all) |
+| `remember` | store a memory (`--type --hubs --link kind:target --label --dedupe`) |
+| `recall` | recall a relevant subgraph (`--limit --json --lexical`) |
+| `wakeup` | compact wake-up pack (identity + open loops + recent) |
+| `pin` | pin/unpin an atom as a standing directive (`--off`) |
+| `directives` | show the standing directives re-injected every turn |
+| `embed` | backfill local embeddings (idempotent; `--force --limit`) |
+| `dreams` | run a dream pass (`--phase light\|rem\|deep\|all`, `--replay YYYY-MM-DD`) |
+| `reflect` | run the weekly reflection pass (re-authors the persona docs) |
+| `forget` | delete a memory by id |
+| `link` | wire two memories (`kind`: supersedes, derived-from, caused-by, consolidates, about) |
+| `consolidate` | dream pass on demand (merge hubs, promote patterns) |
+| `feedback` | record a quality signal (`used\|useful\|noise`) |
+
+## API
+
+Read-mostly JSON; groups worth knowing (full schema at `/api/schema`):
+
+- `/api/mind/*` — `stats`, `graph`, `atom/{id}`, `activity`, `memories`,
+  `recall`, `wakeup`, `directives`, `pin`, `remember`, `feedback`,
+  `consolidate`, `dreams`, `reader`, `import`.
+- `/api/debug/*` — `requests` (rolling trace of every `/api` call),
+  `injections` (plugin lane pushes, GET/POST), `overview` (rank states,
+  mind ops, feedback, ingest runs, life phases, self/soul trace, config).
+- Plus `/api/health`, `/api/stats`, `/api/events`, `/api/sessions`,
+  `/api/search`, `/api/docs`, `/api/ingest/run`.
+
+## Testing
+
+```bash
+.venv/bin/python -m pytest -q
+```
+
+117 tests passing (verified 2026-10-02), including rank calibration and
+parity tests against the old timeline oracle (`tests/parity/`). Ranking
+correctness is covered directly (`test_recall_rank.py`, `test_rank_*.py`).
+There is no published retrieval benchmark (recall@k / MRR) yet — until one
+exists, treat α as a starting point and tune it on your own store
+(`recall --lexical` vs. hybrid makes the comparison by hand).
+
+## Status
+
+Active development. Sprints S0–S7 are done (core mind, Observatory, plugin,
+rank, life loop, API/CLI wiring, cutover — see `SPEC.md` §14 for the board
+and [`docs/CUTOVER.md`](./docs/CUTOVER.md) for the migration). S8 (npm
+launcher + PyInstaller packaging) is pending, so there is no published
+package yet — install from this repo.
+
+## License
+
+[MIT](./LICENSE)

neobrain_cli-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "neobrain-cli"
+version = "0.1.0"
+description = "A simulated brain for AI agents: memory, rank-based forgetting, dreams and a self-authored soul."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { file = "LICENSE" }
+keywords = ["ai-agents", "memory", "mcp", "claude-code", "opencode", "self-hosted", "local-first", "llm", "durable-objects", "embedding"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Build Tools",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+    "pydantic>=2.7",
+    "python-dotenv>=1.0",
+]
+
+[project.urls]
+Homepage = "https://neobrain.alionix.com"
+Repository = "https://github.com/fakiho/neobrain"
+Documentation = "https://github.com/fakiho/neobrain#readme"
+Changelog = "https://github.com/fakiho/neobrain/releases"
+
+[project.scripts]
+neobrain = "neobrain.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "httpx>=0.27"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/neobrain"]
+
+[tool.hatch.build]
+include = [
+  "src/neobrain/**",
+  "README.md",
+  "LICENSE",
+]
+exclude = [
+  "**/__pycache__",
+  "**/*.pyc",
+  "*/.env*",
+  "*/.wrangler/**",
+  "*/.github/**",
+  "tests/**",
+  "web/**",
+  "website/**",
+  "adapters/**",
+  "docs/**",
+  "SPEC.md",
+  "wrangler.jsonc",
+  ".gitignore",
+]
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "standard"        # tightened to strict for new modules (rank/life/runtime)
+pythonVersion = "3.12"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

neobrain_cli-0.1.0/src/neobrain/__init__.py

@@ -0,0 +1,3 @@
+"""neoBrain — a simulated brain for AI agents."""
+
+__version__ = "0.1.0"