aizo-node 0.3.0 → 1.0.0

package/README.md

@@ -1,5 +1,7 @@
 # aizo 爱憎
 
+![aizo — preference memory for AI agents](assets/aizo-hero.png)
+
 [中文文档](README.zh.md)
 
 **aizo** (爱憎, *ài zēng*, "love and hate") is a lightweight, high-performance preference memory system for AI agents, built entirely in Rust.
@@ -10,62 +12,58 @@ It mimics human cognitive memory: rather than storing full conversation transcri
 
 ## How it fits together
 
-aizo is designed for two complementary usage loops:
+aizo is designed around two complementary patterns:
 
 ```
 ╔══════════════════════════════════════════════════════════════════════╗
 ║  1. In-session  (reactive — detects specific emotions in real time)  ║
 ╚══════════════════════════════════════════════════════════════════════╝
 
-   user ──► Claude Code ─────── aizo add ──────────────────┐
-                                                           ▼
-                             CLAUDE.md ◄── contributes ── local SQLite
-                                                      (user preference)
+   user ──► agent ─────── aizo add ──────────────────┐
+                                                     ▼
+                       CLAUDE.md ◄── contributes ── local SQLite
+                                                (user preference)
 
 
 ╔══════════════════════════════════════════════════════════════════════╗
-║  2. Background  (cron task — batch-analyzes accumulated sessions)    ║
+║  2. Just-in-time recall  (on-demand — pulls relevant prefs per task) ║
 ╚══════════════════════════════════════════════════════════════════════╝
 
-   user ──► openclaw ──► sessions ─── aizo analyze ─────────┐
-                                                            ▼
-   USER.md, SOUL.md, IDENTITY.md … ◄── contributes ── local SQLite
-                                                      (user preference)
+   agent gets task ──► aizo recall --scenario coding ──► session context
+                                                              │
+                                                              ▼
+                                                  generate with preferences
 ```
 
 **Loop 1 — In-session:** the agent detects a strong preference signal mid-conversation
-(praise, complaint, explicit rule) and calls `aizo add` immediately. The updated SQLite
-profile is then injected into `CLAUDE.md` (or equivalent context file) so the next
-session starts with the latest understanding of the user.
+(praise, complaint, explicit rule) and calls `aizo add` immediately. Key preferences
+that should persist across all sessions are written into `CLAUDE.md` or `MEMORY.md`.
 
-**Loop 2 — Background:** other agents (openclaw, etc.) accumulate session transcripts
-over time. A scheduled cron job runs `aizo analyze` to extract implicit preferences the
-reactive loop may have missed. The enriched profile is then written into richer identity
-files — `USER.md`, `SOUL.md`, `IDENTITY.md` — that build a persistent, evolving
-picture of the user across all agents and tools.
+**Loop 2 — Just-in-time recall:** not all preferences belong in persistent context files.
+The agent classifies each incoming task into a scenario, calls `aizo recall --scenario <X>`,
+and injects only the relevant preferences into the current session context. This keeps
+the agent's base context lean while giving it access to the full preference profile —
+just like human working memory.
 
-The two loops reinforce each other: reactive writes give immediate recall accuracy;
-batch analysis fills in the gaps and stabilises scores over time.
+For batch analysis of historical sessions to discover new preferences, see SOP 6 in
+`skills/aizo-sop.md` — this is a skill-level concern, not a built-in aizo command.
 
 ---
 
 ## Core design
 
 ```
-session transcript
+agent observation  (praise, complaint, rule, habit)
        │
        ▼
-  flash LLM (claude-haiku-4-5)
-       │  semantic extraction
-       ▼
-  structured entries  { category, item, base_score 0–10 }
-       │  smooth merge
+  aizo add  { item, base_score 0–10, keywords, scenarios }
+       │  smooth merge  (old×0.4 + new×0.6)
        ▼
   SQLite (~/.aizo/preferences.db)
        │
        ▼
   effective_weight = s · d(t)^α   (score-modulated decay)
-       │  keyword or top-N recall
+       │  keyword / score-band / scenario recall
        ▼
   agent reads profile → personalizes response
 ```
@@ -74,19 +72,19 @@ session transcript
 
 All scoring logic lives in `src/scoring/mod.rs`. Every preference entry carries three computed fields, derived at read time from its `base_score` and `last_seen` timestamp.
 
-**Step 1 — Decay coefficient** $d(t)$
+**Step 1 — Decay coefficient d(t)**
 
 $$d(t) = \phi + (1 - \phi) \cdot e^{-\lambda t}, \quad \lambda = \frac{\ln 2}{t_{1/2}}$$
 
-where $t$ is days since `last_seen`, $t_{1/2}$ is the configured half-life, and $\phi$ is the floor.
+where t is days since `last_seen`, t½ (half-life) is the configured half-life, and φ (floor) is the minimum decay.
 
-**Step 2 — Score-dependent exponent** $\alpha$
+**Step 2 — Score-dependent exponent α**
 
 $$\alpha = \frac{10 - s}{10}$$
 
-Higher score → smaller $\alpha$ → decay has less effect. A score-10 preference ($\alpha = 0$) is fully decay-resistant; a score-0 entry ($\alpha = 1$) decays at full speed.
+Higher score → smaller α → decay has less effect. A score-10 preference (α = 0) is fully decay-resistant; a score-0 entry (α = 1) decays at full speed.
 
-**Step 3 — Effective weight** $w$
+**Step 3 — Effective weight w**
 
 $$w = s \cdot d(t)^{\alpha}$$
 
@@ -96,25 +94,15 @@ $$\boxed{w = s \cdot \left[\phi + (1-\phi) \cdot e^{-\lambda t}\right]^{\frac{10
 
 **Boundary behaviour**
 
-| Score $s$ | $\alpha$ | Decay effect | Interpretation |
+| Score s | α | Decay effect | Interpretation |
 |---|---|---|---|
-| 10 | 0.0 | None — $d^0 = 1$ | Core value, never fades |
+| 10 | 0.0 | None (d⁰ = 1) | Core value, never fades |
 | 7  | 0.3 | Slight | Strong preference, slow fade |
 | 5  | 0.5 | Moderate | Neutral habit, fades at half speed |
 | 1  | 0.9 | Near-full | Weak aversion, fades quickly |
-| 0  | 1.0 | Full | $w = 0$ always — absolute zero |
-
-Entries are **never hard-deleted by decay** — they sink toward the floor and persist as weak long-term memory. Use `--type taboo` to surface them explicitly regardless of effective weight.
+| 0  | 1.0 | Full (w = 0) | Absolute zero |
 
-### Scoring scale (0–10)
-
-| Score | Meaning |
-|---|---|
-| 0 | Absolute taboo / hard rejection |
-| 1–3 | Clear dislike / aversion |
-| 4–6 | Neutral tendency / weak pattern |
-| 7–9 | Clear preference |
-| 10 | Strong, consistent, high-priority love |
+Entries are **never hard-deleted by decay** — they sink toward the floor and persist as weak long-term memory. Use `aizo recall --type taboo` to surface hard limits regardless of effective weight.
 
 ### Score smoothing
 
@@ -128,19 +116,33 @@ new_base_score = old_base_score × 0.4 + incoming_score × 0.6
 
 ## Installation
 
-### From source (Rust ≥ 1.70)
-
 ```bash
+# Cargo (recommended)
+cargo install aizo
+
+# npm / npx
+npm install -g aizo
+npx aizo top 10
+
+# From source (Rust ≥ 1.70)
 git clone https://github.com/mmmarcinho/aizo
-cd aizo
-cargo build --release
+cd aizo && cargo build --release
 cp target/release/aizo /usr/local/bin/aizo
 ```
 
+### Configuration
+
+Set env vars in `~/.aizo/.env` (user-wide) or `./.env` (per-project). Shell env always wins.
+
 ```bash
-export ANTHROPIC_API_KEY=sk-ant-...   # required for 'analyze'
+# Only AIZO_DB_PATH is needed for basic use (add/recall/top/show)
+export AIZO_DB_PATH=~/.aizo/preferences.db
 ```
 
+| Variable | Default | Description |
+|---|---|---|
+| `AIZO_DB_PATH` | `~/.aizo/preferences.db` | SQLite database path |
+
 ---
 
 ## CLI reference
@@ -151,20 +153,35 @@ aizo [--db <path>] <COMMAND>
 
 | Command | Description |
 |---|---|
-| `analyze [file]` | Analyze session file or JSON export with flash LLM |
-| `recall [query] [--type …] [--limit N] [--scenario …]` | Keyword + score-range recall — **primary agent call** |
-| `top [N] [--type …]` | Top-N entries by effective weight (default 10) |
-| `show` | Full profile sorted by effective weight |
-| `add <item> <reason> [--score N]` | Manually add or update a preference |
-| `tag <item> <keywords…>` | Add or replace keywords on an existing entry |
-| `touch <item…>` | Reset decay clock without changing score |
+| `recall [query]` | Keyword + score-range recall — **primary agent call** |
+| `top [N]` | Top-N entries by effective weight (read-only, default 10) |
+| `show` | Full profile sorted by effective weight (read-only) |
+| `add <item> <reason>` | Manually add or update a preference |
+| `update <item>` | Update fields on an existing entry (item, reason, score, keywords, scenarios) |
+| `apply <id…>` | Mark recalled entries as actually used; refreshes decay with a 12-hour cooldown |
+| `touch <item…>` | Reset decay clock by item label, subject to the same 12-hour cooldown |
 | `remove <item…>` | Hard-remove an entry |
 | `keywords` | List all stored keywords with entry counts |
-| `clear` | Wipe entire profile and session history |
-| `info` | DB path, score distribution, decay settings |
-| `config show` | Print decay configuration |
-| `config set-half-life <days>` | Set decay half-life |
-| `config set-floor <0.0–1.0>` | Set minimum decay floor |
+| `scenarios` | List all scenarios with entry counts and configured keywords |
+| `clear` | Wipe entire preference profile |
+| `info` | DB path, score distribution, env config, decay settings |
+| `config show/set-half-life/set-floor` | Get or set decay parameters |
+
+**`recall` flags:**
+
+| Flag | Description |
+|---|---|
+| `--type/-t <types>` | Score-range filter, comma-separated: `preference`, `style`, `habit`, `aversion`, `taboo` |
+| `--limit/-l <N>` | Cap results after sorting by effective weight |
+| `--scenario <name>` | Scenario-tagged recall + keyword expansion from `~/.aizo/scenarios.yaml` |
+| `--min-score <N>` | Minimum `base_score` threshold (0.0–10.0); clamps band lower bounds |
+| `--touch` | Refresh matched entries, subject to the 12-hour cooldown; recall is read-only by default |
+| `--no-touch` | Deprecated no-op kept for older scripts |
+| `--json` | Output raw JSON instead of human-readable text |
+
+**`top` flags:** `--type/-t`, `--scenario`, `--json`. Read-only — never touches `last_seen`.
+
+**`show` flags:** `--json` only. Read-only — never touches `last_seen`.
 
 ### Score guide
 
@@ -186,15 +203,11 @@ aizo recall --type taboo               # all hard limits, no keyword needed
 aizo top 5 --type preference
 ```
 
-Use keywords (`--keywords` on add, or `aizo tag`) to add any taxonomy you want.
+Use keywords (`--keywords` on add, or `aizo update --keywords`) to add any taxonomy you want.
 
 ### Examples
 
 ```bash
-# Analyze a session log
-aizo analyze ./chat.txt
-cat conversation.md | aizo analyze
-
 # Agent recalls preferences before generating
 aizo top 5
 aizo recall "code style"
@@ -202,24 +215,30 @@ aizo recall "code style"
 # Scenario-aware recall for coding tasks (expands to ~10 coding keywords)
 aizo recall --scenario coding --type preference,style,habit,taboo --limit 20
 
+# Mark only the preferences the agent actually used
+aizo apply 3 8 12
+
 # Type-only recall (no keyword — returns all entries in that score range)
 aizo recall --type taboo                        # all hard limits
 aizo recall code --type preference --limit 10   # top coding preferences
 aizo recall code --type preference,habit --limit 20  # multiple types
 
-# Inspect full profile
+# Custom minimum score threshold
+aizo recall --scenario coding --min-score 5.0 --limit 20
+
+# Inspect full profile or top-N
 aizo show
+aizo top 20 --scenario coding --json
 
 # Manual entries — score encodes sentiment
 aizo add "concise code"     "Always asks for shorter implementations"  --score 9.0
 aizo add "verbose comments" "Complained about over-documented code"    --score 1.5
 aizo add "emojis in output" "Explicitly said never use emojis"         --score 0.5
-aizo add "uses dark mode"   "Mentioned dark theme in every UI session" --score 5.0
-aizo add "terse naming"     "Consistently chose short variable names"  --score 8.0
+aizo add "uses dark mode"   "Mentioned dark theme in every UI session" --score 5.0 --scenarios coding
 
-# Add or manage keywords for richer recall
-aizo tag "concise code" brevity minimal short lean
-aizo tag "verbose comments" verbosity docs comments over-engineering
+# Update an existing entry
+aizo update "concise code" --score 8.5 --keywords brevity,minimal,short
+aizo update "verbose comments" --scenarios coding,writing
 
 # Tune decay (default: half-life 30d, floor 0.1)
 aizo config set-half-life 14
@@ -262,7 +281,8 @@ CREATE TABLE preferences (
     base_score  REAL    NOT NULL DEFAULT 5.0,   -- 0-10
     source      TEXT    NOT NULL DEFAULT 'manual',
     added_at    TEXT    NOT NULL,
-    last_seen   TEXT    NOT NULL                -- resets decay clock on each reinforcement
+    last_seen   TEXT    NOT NULL,               -- resets decay clock on each reinforcement
+    touch_count INTEGER NOT NULL DEFAULT 0
 );
 -- UNIQUE on LOWER(item)
 
@@ -271,12 +291,6 @@ CREATE TABLE decay_config (
     half_life_days  REAL    NOT NULL DEFAULT 30.0,
     floor           REAL    NOT NULL DEFAULT 0.1
 );
-
-CREATE TABLE sessions (
-    id          INTEGER PRIMARY KEY AUTOINCREMENT,
-    analyzed_at TEXT    NOT NULL,
-    extracted   INTEGER NOT NULL DEFAULT 0
-);
 ```
 
 ---
@@ -288,15 +302,31 @@ Any agent can call aizo as a subprocess — no embedding, no vector index, no ru
 ```python
 import subprocess, json
 
+def recall_scenario(scenario: str, min_score: float = 3.0) -> list[dict]:
+    """Just-in-time recall for a specific task scenario."""
+    return json.loads(subprocess.check_output(
+        ["aizo", "recall", "--scenario", scenario,
+         "--type", "preference,style,habit,taboo",
+         "--min-score", str(min_score), "--limit", "20", "--json"]
+    ))
+
 def top_preferences(n: int = 10) -> list[dict]:
     return json.loads(subprocess.check_output(["aizo", "top", str(n), "--json"]))
 
-def recall(query: str) -> list[dict]:
-    return json.loads(subprocess.check_output(["aizo", "recall", query, "--json"]))
+def apply_preferences(ids: list[int]) -> None:
+    """Call after the agent actually used specific recalled preferences."""
+    if ids:
+        subprocess.check_call(["aizo", "apply", *map(str, ids)])
+
+# Just-in-time: before coding, recall coding-specific preferences
+coding_prefs = recall_scenario("coding")
+# Inject into session context — don't write to disk
+context = f"[Coding preferences]\n{json.dumps(coding_prefs, indent=2)}"
+# After generation, apply only the ids that shaped the response.
+apply_preferences([p["id"] for p in coding_prefs[:3]])
 
-# Inject into system prompt before generating
-prefs = top_preferences(10)
-system = f"User preferences:\n{json.dumps(prefs, indent=2)}\n\n{base_system}"
+# Before writing a document, recall writing preferences
+writing_prefs = recall_scenario("writing")
 ```
 
 Or configure `AIZO_DB_PATH` per-project to maintain separate profiles:
@@ -306,6 +336,61 @@ export AIZO_DB_PATH=./project-prefs.db
 aizo show
 ```
 
+### Just-in-time scenario recall
+
+Not all preferences belong in persistent context files like `CLAUDE.md` or `MEMORY.md` —
+those files would grow unboundedly. Instead, use **scenario-based recall** to pull relevant
+preferences on demand, right when the agent receives a task:
+
+```
+agent receives task ──► classify into scenario ──► aizo recall --scenario <X>
+                                                          │
+                                                          ▼
+                                               inject results into session context
+                                                          │
+                                                          ▼
+                                               generate response with preferences applied
+                                                          │
+                                                          ▼
+                                               aizo apply <used ids>
+```
+
+This keeps the agent's base context lean while giving it access to the full preference
+profile. The pattern works like human memory: you don't pre-load every preference into
+working memory — you recall the relevant ones when the situation calls for it.
+
+**Example flow (coding task):**
+
+```bash
+# Agent classifies the user's request as a coding task, then recalls candidates:
+aizo recall --scenario coding --type preference,style,habit,taboo --min-score 3.0 --limit 20 --json
+
+# After generating, mark only the entries that were actually used:
+aizo apply 3 8 12
+```
+
+**Example flow (writing task):**
+
+```bash
+# Agent classifies the user's request as a writing task, then:
+aizo recall --scenario writing --type preference,style,taboo --limit 15 --json
+```
+
+**Creating scenario-specific entries.** When the user expresses a preference that only
+applies to a certain context, tag it with that scenario so it surfaces only for relevant
+tasks:
+
+```bash
+aizo add "no emojis in code" "Rejected emoji in a PR comment" --score 1.5
+aizo update "no emojis in code" --scenarios coding,review
+
+aizo add "use active voice" "Praised direct, active-voice writing" --score 8.5
+aizo update "use active voice" --scenarios writing
+```
+
+The agent then only sees "no emojis in code" when coding — not when writing casual messages.
+This scoped recall prevents preference leakage across unrelated task domains.
+
 ---
 
 ## Standard Operating Procedure (SOP)
@@ -315,7 +400,7 @@ The SOP for how an agent should use aizo is defined as a skill file at
 (e.g. `.claude/skills/` for Claude Code) and any agent in that project will
 automatically follow the protocol.
 
-The skill defines six triggers:
+The skill defines seven triggers:
 
 | # | Trigger | aizo call | Timing |
 |---|---|---|---|
@@ -323,15 +408,15 @@ The skill defines six triggers:
 | 2 | User shows negative feedback | `aizo add … --score 1.5` then `aizo recall <topic>` | Sync, before corrected reply |
 | 3 | User praises something | `aizo add … --score 9.0` | Async, after reply sent |
 | 4 | User states an explicit rule | `aizo add … --score 0.5` or `--score 10` | Sync, immediate |
-| 5 | About to generate on topic X | `aizo recall <X>` | Sync, before generation |
-| 6 | Session ends | `aizo analyze <transcript>` | Async, background |
-| 7 | Daily cron job | Agent LLM scans logs → `aizo touch` confirmed items | Scheduled, background |
+| 5 | About to generate on topic X | Classify task → `aizo recall --scenario <X> --min-score 3.0` → inject → `aizo apply <used ids>` | Sync recall before generation, apply after |
+| 6 | Historical batch analysis | Agent LLM scans past sessions → `aizo add` new + `aizo apply`/`touch` confirmed | Scheduled, background |
+| 7 | Daily cron job | Agent LLM scans logs → `aizo apply`/`touch` confirmed items | Scheduled, background |
 
 **Key rules encoded in the skill:**
 - Taboos always win over preferences in conflicts
-- `analyze` is for full sessions, not single messages — it calls an LLM
 - Silence (`recall` returning nothing) means no data, not neutral preference
 - Never mention aizo to the user — it runs silently
+- Use scenario recall for just-in-time context; don't dump everything into CLAUDE.md
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aizo-node",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "爱憎 — preference memory for AI agents: extract, decay, and recall user likes and dislikes",
   "license": "MIT",
   "repository": {
@@ -21,6 +21,7 @@
   "files": [
     "install.js",
     "run.js",
-    "README.md"
+    "README.md",
+    "assets"
   ]
 }