omo-memory 0.1.11 → 0.1.13

package/docs/adapter-integration.md

@@ -32,6 +32,7 @@ npx -y omo-memory session bootstrap --host codex --adapter lazycodex --limit 5
 npx -y omo-memory session start --host codex --adapter lazycodex
 npx -y omo-memory session start --host grok --adapter lfg
 npx -y omo-memory recent --limit 10
+npx -y omo-memory recall --query "current roadmap decision" --limit 10
 ```
 
 For a source checkout:
@@ -45,6 +46,7 @@ node dist/cli.js event record --type decision --summary "Use OMO Memory as the s
 node dist/cli.js event record --type qa_evidence --summary "CLI smoke passed for init/session/event/recent."
 node dist/cli.js handoff write --summary "Continue from recent decision and qa_evidence events."
 node dist/cli.js recent --limit 10
+node dist/cli.js recall --query "qa evidence" --limit 10
 node dist/cli.js export
 node dist/cli.js purge --yes
 ```
@@ -85,7 +87,7 @@ Register the same MCP server in every host that needs memory access. Do not crea
 
 ## Session Bootstrap Flow
 
-At the beginning of a Codex, OpenCode, or Grok adapter session, call `memory_bootstrap_session` instead of separately calling `memory_start_session` and `memory_recent_events`.
+At the beginning of a Codex, OpenCode, or Grok adapter session, call `memory_bootstrap_session` only when the adapter needs a session id for subsequent writes. Do not use bootstrap as a prompt-time memory injection hook.
 
 ```json
 {
@@ -102,9 +104,8 @@ The tool returns:
 
 - `sessionId`: the new session row for subsequent event/handoff writes.
 - `project`: the current git/project namespace.
-- `recentEvents`: recent events from the same project namespace.
 
-During the session, write concise task state and evidence with the returned `sessionId`:
+During the session, hooks should write concise user-action summaries, task state, decisions, and evidence with the returned `sessionId`:
 
 ```json
 {
@@ -119,6 +120,13 @@ During the session, write concise task state and evidence with the returned `ses
 
 This package is the local MCP-to-SQLite router. It does not scrape host transcripts or centralize cloud state. Hosts and adapters must call the MCP tools at their own lifecycle points.
 
+Retrieval is opt-in or intent-gated:
+
+- Use `memory_recent_events` only when the user explicitly asks for recent OMO Memory context.
+- Use `memory_recall_events` when the current user input has a concrete query that can be matched to recorded summaries, decisions, or evidence.
+- Do not automatically attach the last session to every user prompt.
+- Do not store raw user prompts by default; record concise, redacted action summaries.
+
 Use these tools:
 
 - `memory_init`
@@ -127,9 +135,58 @@ Use these tools:
 - `memory_start_session`
 - `memory_record_event`
 - `memory_recent_events`
+- `memory_recall_events`
 - `memory_write_handoff`
 - `memory_export`
 - `memory_purge`
+- `memory_global_scan`
+- `memory_global_migrate`
+- `memory_global_list`
+- `memory_ontology_candidates`
+- `memory_ontology_extract`
+- `memory_ontology_score`
+- `memory_ontology_promote`
+- `memory_ontology_demote`
+- `memory_ontology_supersede`
+- `memory_ontology_recall`
+
+CLI updates: normal CLI commands automatically launch a quiet background `npm install -g omo-memory@latest` at most once per day. MCP startup intentionally does not auto-update because stdout/stderr must remain reserved for the protocol. Hosts that need pinned installs should set `OMO_MEMORY_AUTO_UPDATE=0` in the CLI environment.
+
+Global migration is copy/import only. Adapters may scan for existing project-local `.omo/memory/state.sqlite` databases and import them into a user-selected global SQLite file, but they must preserve source DBs and retain source provenance in the global store.
+
+Global migration also materializes an aggregate OMO schema view inside the global SQLite file. This lets existing ontology extraction, retention scoring, recall, and OpenTUI graph code operate on integrated cross-project events while `global_*` tables retain source database provenance.
+
+Example global second-brain flow:
+
+```sh
+omo-memory global scan --root /Users/ilseoblee/workspace
+omo-memory global migrate --root /Users/ilseoblee/workspace --global-db ~/.omo/memory/global.sqlite
+OMO_MEMORY_DB=~/.omo/memory/global.sqlite omo-memory ontology candidates
+OMO_MEMORY_DB=~/.omo/memory/global.sqlite omo-memory ontology score
+bun --version
+omo-memory graph tui --db ~/.omo/memory/global.sqlite --query linaforge
+```
+
+`graph tui` requires `bun` on `PATH` for the OpenTUI terminal renderer. Other CLI and MCP commands run on Node.
+
+Lifecycle commands:
+
+- `memory_ontology_candidates`: derive candidate terms from concise summaries.
+- `memory_ontology_extract`: explicitly extract candidates from one summary/event.
+- `memory_ontology_score`: recompute deterministic scores and retention classes.
+- `memory_ontology_promote`: curate a concept into durable memory.
+- `memory_ontology_demote`: lower a durable memory's retention class.
+- `memory_ontology_supersede`: preserve the old memory and create a replacement.
+- `memory_ontology_recall`: retrieve ontology-backed memories only for an explicit query.
+
+OpenTUI graph controls:
+
+- `q`: quit.
+- `Up` / `Down`: move selected concept.
+- `Tab`: move to the next concept.
+- `/` or `f`: focus filter input when supported by the terminal runtime.
+
+The graph UI is local terminal UI. It does not require a browser, web server, cloud account, or vector service.
 
 Example session start:
 
@@ -162,3 +219,58 @@ Example QA evidence:
 - Store sanitized summaries and evidence references instead of full logs.
 - Host-specific values may appear only in small redacted metadata payloads and must not require schema branches.
 - Export and purge are explicit lifecycle commands; purge requires explicit confirmation.
+
+## Ontology Schema Boundary
+
+OMO Memory's chronological ledger remains authoritative: sessions, events, and handoffs record what happened in a project. The ontology schema is an additive layer for durable memory derived from that ledger:
+
+- `concepts` stores vocabulary entries such as project terms, practices, tools, and recurring ideas.
+- `relations` stores typed links between concepts, decisions, events, sessions, and handoffs.
+- `durable_memories` stores approved long-term facts, preferences, and working rules.
+- `decision_records` stores important choices with rationale, evidence, status, reversibility, and provenance.
+
+Adapters must treat ontology rows as curated local memory, not as raw capture. Do not write full transcripts, raw logs, `.env` contents, auth files, cookies, bearer headers, or secret-bearing payloads into ontology tables. User-authored text must pass through the same redaction boundary used by event and handoff writes before it is promoted into durable memory.
+
+The ontology layer is intentionally not a new adapter surface by itself. CLI and MCP commands should continue to call shared core functions, and future concept/decision commands must not create host-specific schemas or side databases.
+
+## Retention Scoring Policy (Deterministic Contract)
+
+Retention classification is strictly deterministic. There is no ML, embeddings, or hidden model. A pure function maps explicit signals to a numeric score and then to one of five classes.
+
+Classes (in ascending durability):
+
+- `forget`: score < 30 (or after decay/contradiction). Safe to drop.
+- `temporary`: 30 <= score < 50. Short-term context only.
+- `working`: 50 <= score < 75. Active task/iteration memory.
+- `durable`: 75 <= score < 90. Cross-session value; survives typical decay.
+- `permanent`: score >= 90, or any manually pinned item. Manual pin is a hard override.
+
+Manual pin rule (critical): an item with `manualPin: true` is always classified `permanent` regardless of raw score, age, or frequency. Decay jobs and age-based expiration MUST NOT remove or downgrade pinned permanent memory; only explicit supersede/demote/purge may change it.
+
+### Score Formula (pure, exposed)
+
+Exported constants (see `src/retentionPolicy.ts`):
+
+- `RETENTION_CLASSES = ["forget", "temporary", "working", "durable", "permanent"] as const`
+- `RETENTION_THRESHOLDS = { forget: 0, temporary: 30, working: 50, durable: 75, permanent: 90 } as const`
+- `RETENTION_WEIGHTS = { frequency: 4.5, spread: 7, decision: 12, qa: 10, relation: 4, confidence: 10, recencyBase: 18, recencyPerDay: 0.55, agePerDay: 0.12, ageCap: 22, contradiction: 9 } as const`
+
+```
+score = clamp(
+  frequency * 4.5
+  + spread * 7
+  + decisionWeight * 12
+  + qaWeight * 10
+  + relationDegree * 4
+  + confidence * 10
+  + max(0, 18 - recencyDays * 0.55)
+  - min(22, ageDays * 0.12)
+  - contradictionCount * 9
+, 0, 110)
+```
+
+`computeRetentionScore(input)` returns the rounded integer. `classifyRetention(score, manualPin)` returns the class, applying the pin override first.
+
+Boundary cases (score, pin=false): 29→forget, 30→temporary, 49→temporary, 50→working, 74→working, 75→durable, 89→durable, 90→permanent. These are verified by the focused contract test.
+
+All scoring inputs are derived from ledger signals (event counts, last-seen deltas, project spread from index, decision/qa event types, explicit relation degree, stored confidence, manual pin flag, contradiction markers). No raw transcripts or secrets are inputs.

package/docs/epic-omo-memory.md

@@ -1,13 +1,13 @@
-# Epic: OMO Memory — shared local session DB for OMO adapters
+# Epic: OMO Memory — shared local second-brain DB for OMO adapters
 
 ## Goal
 
-Build a host-neutral local memory layer for OMO so lazycodex, omo-on-opencode, lfg, and future adapters can share task context across coding-tool sessions.
+Build a host-neutral local memory layer for OMO so lazycodex, omo-on-opencode, lfg, and future adapters can share task context, durable decisions, and ontology-backed project knowledge across coding-tool sessions.
 
 The product ships as both:
 
-- CLI: install, inspect, search, export, purge, and handoff operations.
-- MCP server: standard stdio tools for agents and coding tools to read/write OMO memory.
+- CLI: install, inspect, global migration, ontology lifecycle, graph, search, export, purge, and handoff operations.
+- MCP server: standard stdio tools for agents and coding tools to explicitly read/write OMO memory.
 
 ## Problem
 
@@ -18,32 +18,64 @@ Codegraph solves code intelligence, not work/session memory. OMO needs a separat
 ## Product direction
 
 - Project-local DB: `<project-root>/.omo/memory/state.sqlite`
+- Optional global DB: user-selected SQLite path such as `~/.omo/memory/global.sqlite`, populated by copy/import from local project ledgers
 - Project namespace: derive from git remote + repo root hash, with branch/head metadata
 - Local-first privacy: no cloud sync and no secret storage by default
 - Adapter-neutral schema: `host` and `adapter` are metadata, not separate products
 - Shared API: CLI and MCP use the same core DB layer
+- Second-brain lifecycle: candidate extraction, deterministic retention scoring, promotion, demotion, supersession, explicit recall, and OpenTUI graph inspection
 
 ## In scope
 
 - SQLite schema and migrations
 - CLI commands:
   - `init`
+  - `global scan`
+  - `global migrate`
   - `session start`
+  - `session bootstrap`
   - `event record`
   - `recent`
+  - `recall`
   - `handoff write`
   - `doctor`
+  - `ontology candidates`
+  - `ontology score`
+  - `ontology promote`
+  - `ontology demote`
+  - `ontology supersede`
+  - `ontology recall`
+  - `graph tui`
 - MCP stdio server with tools:
   - `memory_init`
   - `memory_project_context`
+  - `memory_bootstrap_session`
+  - `memory_start_session`
   - `memory_record_event`
   - `memory_recent_events`
+  - `memory_recall_events`
   - `memory_write_handoff`
+  - `memory_global_scan`
+  - `memory_global_migrate`
+  - `memory_global_list`
+  - `memory_ontology_candidates`
+  - `memory_ontology_extract`
+  - `memory_ontology_score`
+  - `memory_ontology_promote`
+  - `memory_ontology_demote`
+  - `memory_ontology_supersede`
+  - `memory_ontology_recall`
 - Privacy guardrails:
   - local-only default
   - no API key/token/env capture
   - explicit purge/export commands
 - Adapter integration notes for lazycodex, omo-on-opencode, and lfg
+- Retention classes:
+  - `forget`: safe to drop after low score or decay
+  - `temporary`: short-term task context
+  - `working`: active project memory
+  - `durable`: cross-session knowledge
+  - `permanent`: manual-pin or high-score knowledge; only explicit demote/supersede/purge changes it
 
 ## Out of scope
 
@@ -51,6 +83,8 @@ Codegraph solves code intelligence, not work/session memory. OMO needs a separat
 - Team sharing by default
 - Full transcript capture by default
 - Vector/embedding search in MVP
+- Browser-only graph UI
+- Automatic prompt injection from the last session
 - Replacing codegraph
 - Host-specific private APIs as required dependencies
 
@@ -59,33 +93,51 @@ Codegraph solves code intelligence, not work/session memory. OMO needs a separat
 ### CLI
 
 - `omo-memory init` creates or migrates `<project-root>/.omo/memory/state.sqlite`.
+- `omo-memory global scan --root <path>` discovers project-local OMO DBs and reports schema versions.
+- `omo-memory global migrate --root <path> --global-db <path>` copies source DB data into one global SQLite file without mutating source DBs.
 - `omo-memory session start --host grok --adapter lfg` records a session for the current project.
+- `omo-memory session bootstrap --host codex --adapter lazycodex` returns a session id and project metadata without injecting recent events.
 - `omo-memory event record --type decision --summary "..."` appends a project/session event.
 - `omo-memory recent` lists recent project events.
+- `omo-memory recall --query "..."` performs explicit query-gated event recall.
 - `omo-memory handoff write --summary-file path.md` stores a handoff summary.
+- `omo-memory ontology candidates` extracts vocabulary candidates from concise summaries.
+- `omo-memory ontology score` recomputes deterministic retention classes.
+- `omo-memory ontology promote/demote/supersede/recall` supports curated durable memory lifecycle.
+- `omo-memory graph tui --db <path> --query <term>` opens an OpenTUI graph with `q` quit, arrow/tab selection, retention class, score, provenance, and detail pane. It requires `bun` on `PATH`; other CLI and MCP commands run on Node.
 
 ### MCP
 
 - `omo-memory mcp` starts a stdio MCP server.
-- MCP tools can initialize the DB, read project context, record events, list recent events, and write handoffs.
+- MCP tools can initialize the DB, read project context, record events, list/retrieve explicit memory, write handoffs, migrate global memory, and manage ontology lifecycle.
 - MCP tool responses are structured JSON text.
+- `memory_bootstrap_session` remains write-only/session-only and does not return `recentEvents`.
 
 ### Privacy and safety
 
 - No secrets are read from `.env`, auth files, or host config by default.
 - DB path can be overridden only by explicit `OMO_MEMORY_DB`.
 - `doctor` reports DB path, schema version, and project identity without leaking sensitive values.
+- Global migration is copy/import only; source project DB mtimes and row counts must remain unchanged.
+- Graph and recall are local-first and explicit; no cloud sync, browser server, raw transcript capture, or embeddings are required.
 
 ### QA evidence
 
 - `npm run typecheck`
 - `npm run build`
+- `npm run check`
 - CLI smoke:
   - `node dist/cli.js init`
+  - `node dist/cli.js global scan --root <tmp-workspace>`
+  - `node dist/cli.js global migrate --root <tmp-workspace> --global-db <tmp-global.sqlite>`
   - `node dist/cli.js session start --host grok --adapter lfg`
   - `node dist/cli.js event record --type decision --summary "smoke"`
+  - `node dist/cli.js ontology candidates`
+  - `node dist/cli.js ontology score`
+  - `bun dist/cli.js graph tui --db <tmp-db> --query smoke`
   - `node dist/cli.js recent`
 - MCP smoke: start `node dist/cli.js mcp` and verify `tools/list` includes memory tools.
+- Backfill verifier: synthetic Linaforge/omo-memory/lfg/omo-phone DB replicas plus read-only scan of real local DB paths.
 
 ## Follow-up issue breakdown
 
@@ -94,5 +146,9 @@ Codegraph solves code intelligence, not work/session memory. OMO needs a separat
 3. MCP stdio server
 4. Project identity and git metadata
 5. Privacy/redaction/purge/export
-6. Adapter integration docs for lazycodex, omo-on-opencode, and lfg
-7. QA harness for CLI and MCP smoke tests
+6. Global SQLite migration and source provenance
+7. Deterministic ontology extraction and retention scoring
+8. Durable memory promote/demote/supersede lifecycle
+9. OpenTUI graph visualization
+10. Adapter integration docs for lazycodex, omo-on-opencode, and lfg
+11. QA harness for CLI, MCP, global backfill, and TUI smoke tests

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omo-memory",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Host-neutral local SQLite memory and session ledger for OMO adapters, exposed through CLI and MCP.",
   "type": "module",
   "files": [
@@ -24,6 +24,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "postbuild": "chmod 755 dist/cli.js",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "format": "biome format --write .",
@@ -39,6 +40,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opentui/core": "0.4.2",
     "better-sqlite3": "^12.11.1",
     "zod": "^4.4.3"
   },