apsolut-cortex 0.1.0 → 0.1.2

package/README.md

@@ -3,86 +3,105 @@
 Persistent memory for Claude Code projects.
 
 Stores corrections, decisions, and patterns across sessions so Claude stops
-repeating the same mistakes and forgetting what you've already decided.
+repeating the same mistakes and forgetting what you decided last week.
 
 ---
 
-## Install (one time)
+## Install
 
 ```bash
-cd ~/tools
-git clone ... apsolut-cortex
-cd apsolut-cortex
-bun install
+npm install -g apsolut-cortex
 ```
 
 ## Per project
 
 ```bash
-cd ~/your-project
-bun run ~/tools/apsolut-cortex/src/cli.ts init
+cd your-project
+apsolut-cortex init
 ```
 
 Restart Claude Code. Done.
 
+---
+
 ## How it works
 
-**During sessions:**
-- Tool failures and config reads are captured automatically
-- Transcript is scanned for self-corrections when Claude stops
-- Say `"remember <topic>"` to search memory on demand
+Sessions start clean — no context dumped automatically.
+Memory is on demand. Say `"remember <topic>"` and Claude searches.
+
+**During sessions (automatic):**
+- Tool failures captured and stored
+- Config file reads noted as discoveries
+- Transcript scanned for self-corrections when Claude stops
 
-**At session end:**
+**At session end (automatic):**
 - Observations compressed into memories via Claude Haiku
-- If no `ANTHROPIC_API_KEY`: falls back to Ollama, then fails loudly
-- Session summary stored for your own review
-- Stale memories decay, low-value ones get pruned
+- Fallback: Ollama if no API key
+- Session summary stored for continuity
+- Stale memories decay, low-value ones pruned over time
 
-**Memory is on-demand, not pre-loaded.**
-Sessions start clean. Claude uses `memory_search` when it needs context,
-not speculatively at the start of every session.
+---
 
 ## MCP tools Claude can call
 
-| Tool | When to use |
-|------|------------|
-| `memory_search(query)` | "remember auth", "remember what we decided about queues" |
-| `memory_store(content, category, tier)` | After any important discovery or decision |
-| `memory_rate(id, score)` | After using a retrieved memory (0-3) |
+| Tool | When |
+|------|------|
+| `memory_search(query)` | User says "remember X" or Claude is uncertain |
+| `memory_store(content, category, tier)` | After a decision or discovery |
+| `memory_rate(id, score)` | After using a retrieved memory (0–3) |
 | `memory_contradict(id, correction?)` | When a memory is wrong |
 | `memory_status()` | Overview of what's stored |
 
-## Trust levels
-
-`observed` → `validated` → `proven` → `canonical`
-
-Observed: just captured. Validated: rated useful 3+ times. Proven/Canonical: human
-promotion only (future dashboard).
+---
 
 ## Compression providers
 
-1. `ANTHROPIC_API_KEY` → Claude Haiku (recommended)
-2. Ollama at `localhost:11434` → `qwen2.5-coder:7b` by default
-   - Override model: `CORTEX_OLLAMA_MODEL=llama3.1`
-   - Override host: `OLLAMA_HOST=http://...`
-3. Neither available → loud error, observations saved for next session
+Set one of these or cortex will fail loudly at session end:
 
-## Status
+**Option 1 — Anthropic API**
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
 
+**Option 2 — Ollama (free, local, private)**
 ```bash
-bun run ~/tools/apsolut-cortex/src/cli.ts status
+ollama pull qwen2.5-coder:7b
+ollama serve
 ```
 
-## Uninstall
+Override model: `CORTEX_OLLAMA_MODEL=llama3.1`
+Override host: `OLLAMA_HOST=http://localhost:11434`
+
+---
+
+## Commands
 
 ```bash
-bun run ~/tools/apsolut-cortex/src/cli.ts uninstall
+apsolut-cortex init        # set up memory for this project
+apsolut-cortex status      # show what's stored
+apsolut-cortex uninstall   # remove hooks and MCP config
 ```
 
-Memory DB at `~/.apsolut/memory.db` is kept. Delete manually for clean slate.
+---
+
+## Storage
+
+```
+~/.apsolut/
+  ├── memory.db       ← all memories, all projects, SQLite
+  ├── registry.json   ← project registry
+  └── models/         ← embedding model cache (downloads once)
+```
+
+All projects share one DB, namespaced by project UUID.
+No data leaves your machine except what you send to the Anthropic API
+for session compression.
 
 ---
 
-**What this is NOT:** a brain, an agent, a code analyser.
-It is a spine — it carries signals forward across sessions without doing the thinking.
-The intelligence is still Claude's.
+## Memory trust levels
+
+`observed` → `validated` → `proven` → `canonical`
+
+Starts at observed. Promoted automatically as memories prove useful.
+Canonical memories never decay.