@mrc2204/agent-smart-memo 5.0.2 → 5.1.2

package/README.md

@@ -1,373 +1,270 @@
 # Agent Smart Memo
 
-> **ASM v5.1 super memory platform for OpenClaw agents** — unified memory for **conversation memory**, **project memory**, semantic retrieval, structured slots, graph knowledge, onboarding, and engineering context assembly.
+> **ASM v5.1** is a super memory platform for coding agents: **conversation memory + project memory + retrieval/control plane**, delivered through a single package and a CLI-first install flow.
 
-Originally built as an OpenClaw memory plugin for conversation/runtime memory, `agent-smart-memo` has evolved into a broader **agent memory platform**:
+`@mrc2204/agent-smart-memo` provides a project-aware memory layer that can be installed into multiple runtimes while keeping one shared memory/config model.
 
-- **conversation memory** for agent runtime continuity
-- **project memory** for repo-aware engineering context
-- **semantic memory** via vector retrieval
-- **structured slot memory** via SQLite
-- **graph memory** for entities/relationships
-- **operator onboarding** for project registration + Jira mapping + indexing
-- **CLI/setup flows** for OpenClaw installation and bootstrap
-
-This repo is still packaged for **OpenClaw first**, but its practical role is now:
+Today ASM provides:
+- conversation/runtime continuity
+- structured slot memory
+- semantic retrieval
+- graph memory
+- project registry + onboarding
+- repo-aware indexing / reindexing
+- lineage-aware engineering context retrieval
+- CLI-based platform install flows for OpenClaw, Paperclip, and OpenCode
 
-- a **super memory layer** for agents
-- a **project-aware engineering memory system**
-- an **operator-friendly onboarding/runtime package**
+This means ASM is best understood as:
 
-It is no longer accurate to describe ASM as only a small conversation-memory plugin.
+> **a shared memory platform for coding agents, with OpenClaw as the primary runtime and Paperclip/OpenCode as supported adapters**
 
 ---
 
-## 1) What ASM v5.1 is
+## 1) Core mental model
 
-ASM v5.1 combines two big memory domains.
+ASM has 3 practical layers.
 
 ### A. Conversation memory
-Used for ongoing agent continuity and runtime recall:
-- semantic memory (`memory_search`, `memory_store`)
-- structured slot memory (`memory_slot_*`)
-- graph memory (`memory_graph_*`)
-- auto-capture / auto-recall support
-- namespace-aware memory behavior
+Used for runtime continuity:
+- `memory_search`
+- `memory_store`
+- `memory_slot_*`
+- `memory_graph_*`
+- auto-capture / auto-recall
 
 ### B. Project memory
-Used for engineering/project-aware workflows:
-- project registry and aliasing
+Used for engineering context:
+- project registry
 - repo root / repo remote identity
-- Jira mapping and tracker linkage
-- onboarding flows for new repos
-- project indexing / reindexing
-- hybrid retrieval with file / symbol / task lineage
-
-That is why ASM now acts as:
+- project aliasing
+- Jira linkage
+- onboarding + index triggers
+- lifecycle-aware retrieval boundaries
 
-> **conversation memory + project memory + retrieval/control plane in one agent-facing platform**
-
----
-
-## 2) What ASM v5.1 provides today
-
-ASM-69 and follow-up waves expanded the system from memory-only into project-aware memory orchestration.
-
-### Project-aware memory model
-Agents can now reason about:
-- `project_id`
-- project alias
-- `repo_root`
-- `repo_remote`
-- Jira space / epic mapping
-- registration / validation state
-
-### Ingest + semantic block extraction
-Codebases can be transformed into retrievable structures using:
-- file planning
-- semantic block extraction
-- deterministic file/chunk/symbol IDs
-- diff-aware indexing primitives
-
-### Incremental reindex
-Instead of rebuilding everything blindly, ASM now supports:
-- changed / unchanged / deleted diffing
-- watch-state snapshotting
-- checksum-driven reindex control
-- background-friendly trigger flow
-
-### Hybrid retrieval + task lineage
-ASM is not just vector search anymore.
-It can combine:
+### C. Retrieval/control plane
+Used to assemble better context for coding agents:
 - semantic recall
-- lexical/project filters
-- file/symbol/task context
-- parent/related/touched lineage context
+- lexical/project filtering
+- file/symbol/task lineage
+- deterministic project-aware retrieval
+- platform install / bootstrap flows
 
-### Operator onboarding
-Operators can onboard a project with repo + alias + Jira mapping + optional index trigger using project-aware command flows.
+If you only remember one sentence, remember this:
 
-### Setup CLI
-OpenClaw setup is now easier through the global CLI:
-- `asm setup-openclaw`
-- `asm setup openclaw`
-- legacy-compatible `npm run init-openclaw`
+> **ASM is a super memory platform for coding agents: conversation memory + project memory + runtime delivery in one package.**
 
 ---
 
-## 3) Scope of this repository
+## 2) Runtime targets
 
-This repository now spans multiple practical layers.
+### OpenClaw
+Primary target today.
 
-### OpenClaw runtime/plugin layer
 Includes:
-- plugin entry
-- tool registration
-- runtime hooks
-- OpenClaw packaging/build flow
-- setup/bootstrap CLI flow
+- OpenClaw plugin entry
+- tools / hooks / runtime wiring
+- CLI bootstrap flow
+- shared ASM config integration
 
-### Shared memory platform layer
-Includes:
-- SlotDB
-- semantic memory use-cases
-- graph/registry logic
-- shared contracts and runtime abstractions
-
-### Project-aware engineering memory layer
-Includes:
-- project registry
-- onboarding use-cases
-- tracker mapping
-- indexing/reindexing primitives
-- lineage-aware retrieval
-
-So the best mental model is:
-
-> **an OpenClaw-delivered super memory platform with both conversation memory and project memory**
-
----
-
-## 4) Runtime targets
-
-### OpenClaw target
-Use this when you want ASM as the main OpenClaw memory/runtime plugin.
-
-Contains:
-- core memory platform
-- OpenClaw adapter
-- plugin entry / hooks / tool registration
-- operator onboarding command surfaces
-
-Artifact intent:
-- **OpenClaw plugin artifact**
-
-### Paperclip target
-Use this when you want Paperclip to consume the same shared memory core/runtime behavior.
-
-Contains:
-- core memory platform
-- Paperclip adapter/runtime wrapper
-- compatibility mapping
-
-Artifact intent:
-- **Paperclip runtime package**
-
-### Core target
-Use this when you want the shared contracts/use-cases without OpenClaw/Paperclip-specific delivery.
-
-Contains:
-- shared contracts
-- shared use-cases
-- shared memory/platform rules
+Install:
+```bash
+asm install openclaw
+```
 
-Artifact intent:
-- **runtime-agnostic shared memory core**
+### Paperclip
+Uses the same shared memory core through a Paperclip adapter.
 
----
-
-## 5) Main capability areas
+Install:
+```bash
+asm install paperclip
+```
 
-### Conversation memory capabilities
-- `memory_search`
-- `memory_store`
-- `memory_slot_get`
-- `memory_slot_set`
-- `memory_slot_delete`
-- `memory_slot_list`
-- `memory_graph_*`
-- auto-capture / auto-recall
+### OpenCode
+Uses the same package and shared config, with MCP/local runtime wiring.
 
-### Project memory capabilities
-- `project.register`
-- `project.get`
-- `project.list`
-- `project.link_tracker`
-- `project.trigger_index`
-- `project.reindex_diff`
-- `project.index_watch_get`
-- `project.legacy_backfill`
-- Telegram/operator onboarding surfaces
-
-### Retrieval/engineering context capabilities
-- semantic retrieval
-- lexical/project filtering
-- project-aware context assembly
-- file / symbol / task lineage
-- repo-aware indexing and reindexing
+Install:
+```bash
+asm install opencode
+```
 
 ---
 
-## 6) CLI / setup UX
-
-The preferred setup path is the global CLI.
+## 3) Install ASM
 
-### Install globally
+### Global install
 ```bash
 npm install -g @mrc2204/agent-smart-memo
 ```
 
-### Preferred setup flow
+### Initialize shared ASM config
 ```bash
-asm setup-openclaw
+asm init-setup --yes
 ```
 
-Also supported:
-```bash
-asm setup openclaw
+This creates or updates:
+```text
+~/.config/asm/config.json
 ```
 
-Legacy-compatible flow:
+### Install into a platform
 ```bash
-npm run init-openclaw
+asm install openclaw
+asm install paperclip
+asm install opencode
 ```
 
-### What `asm setup-openclaw` does
-1. checks that `openclaw` CLI exists
-2. installs `@mrc2204/agent-smart-memo` if missing
-3. runs OpenClaw bootstrap/init flow
-4. patches config with preview + backup behavior
-5. prints next-step verification guidance
+Legacy compatibility still exists for older OpenClaw flows, but the preferred path is now:
 
-This is the fastest path for operators who want ASM enabled in OpenClaw without manual config editing first.
+```text
+asm init-setup -> asm install <platform>
+```
 
 ---
 
-## 7) Quick start for OpenClaw
+## 4) Shared config source-of-truth
+
+ASM now uses a shared config model.
+
+### Canonical shared config
+```text
+~/.config/asm/config.json
+```
+
+### What lives there
+Core fields such as:
+- `projectWorkspaceRoot`
+- `storage.slotDbDir`
+- `qdrantHost`
+- `qdrantPort`
+- `qdrantCollection`
+- `qdrantVectorSize`
+- `llmBaseUrl`
+- `llmApiKey`
+- `llmModel`
+- `embedBaseUrl`
+- `embedBackend`
+- `embedModel`
+- `embedDimensions`
+- `autoCaptureEnabled`
+- `autoCaptureMinConfidence`
+- `contextWindowMaxTokens`
+- `summarizeEveryActions`
+
+### Platform-local config
+Platform config should stay minimal.
+
+For OpenClaw, `~/.openclaw/openclaw.json` should mainly keep:
+- `enabled`
+- `asmConfigPath`
+- adapter-local overrides only when truly needed
+
+Example OpenClaw plugin entry:
+
+```json
+{
+  "enabled": true,
+  "config": {
+    "asmConfigPath": "/Users/your-user/.config/asm/config.json",
+    "slotDbDir": "/Users/your-user/.openclaw/agent-memo",
+    "projectWorkspaceRoot": "/Users/your-user/Work/projects"
+  }
+}
+```
+
+This keeps `openclaw.json` from becoming a second core source-of-truth.
+
+---
 
-If your current goal is still “install and run ASM in OpenClaw”, use this section.
+## 5) OpenClaw quick start
 
-### Install plugin directly
+### Install from npm
 ```bash
-openclaw plugins install @mrc2204/agent-smart-memo
+npm install -g @mrc2204/agent-smart-memo
+asm init-setup --yes
+asm install openclaw --yes
 ```
 
-### Or install locally from source
+### Install locally from source
 ```bash
 npm install
 npm run build
-openclaw plugins install -l .
+node bin/asm.mjs init-setup --yes
+node bin/asm.mjs install openclaw --yes
 ```
 
-### Prerequisites
-You typically need:
-
-| Service | Purpose | Example |
-|---|---|---|
-| Qdrant | Semantic/vector memory | `docker run -d -p 6333:6333 qdrant/qdrant` |
-| Embedding backend | Embeddings for semantic recall | Ollama / OpenAI-compatible / docker adapter |
-| LLM endpoint | Fact extraction / auto-capture | OpenAI-compatible API |
-
-### Example OpenClaw config
-Add to `~/.openclaw/openclaw.json`:
-
-```json5
-{
-  plugins: {
-    allow: ["agent-smart-memo"],
-    slots: {
-      memory: "agent-smart-memo"
-    },
-    entries: {
-      "agent-smart-memo": {
-        enabled: true,
-        config: {
-          qdrantHost: "localhost",
-          qdrantPort: 6333,
-          qdrantCollection: "openclaw_memory",
-
-          llmBaseUrl: "https://api.openai.com/v1",
-          llmApiKey: "sk-...",
-          llmModel: "gpt-4o-mini",
-
-          embedBaseUrl: "http://localhost:11434",
-          embedBackend: "ollama",
-          embedModel: "qwen3-embedding:0.6b",
-          embedDimensions: 1024,
-
-          slotDbDir: "/Users/your-user/.openclaw/agent-memo"
-        }
-      }
-    }
-  }
-}
+### Verification
+```bash
+npm run test:asm-cli
+npx tsx tests/test-init-openclaw.ts
+npm run build:openclaw
 ```
 
 ---
 
-## 8) Project onboarding flow
+## 6) Project-aware onboarding flow
 
-For project-aware onboarding in OpenClaw/Telegram flows, the current slash command is:
+ASM supports operator-friendly project onboarding.
 
+### Telegram/OpenClaw command
 ```text
 /project <repo_url>
 ```
 
-### Current behavior summary
-- onboarding preview exposes resolved `repo_root` when derivable
-- preview/commit can report `repo_resolution` and `clone_policy`
-- if `repo_url` matches an already-registered remote, registration reuses the existing project identity / `repo_root`
-- if `repo_url` is a local path, it is treated as import without `git clone`
-- `project.trigger_index` is background-friendly and reports:
-  - `accepted`
-  - `enqueued`
-  - `detached`
-  - `job_id`
-
-### Typical onboarding path
-1. operator starts with `/project <repo_url>`
-2. bot prepares preview
-3. preview shows alias/Jira/index choices and repo resolution hints
-4. operator confirms
-5. flow bridges into:
-   - `project_register_command`
-   - `project_link_tracker`
-   - `project_trigger_index`
-
-See also:
-- `docs/architecture/ASM-74-master-project-registration-ux-command-contract-jira-mapping-v5.1.md`
-- `tests/test-project-registry.ts`
+### Current behavior
+- resolves repo path/identity when possible
+- supports local path import without forced clone
+- can reuse an already-registered remote/project identity
+- can attach Jira mapping
+- can trigger background index flow
 
----
+Typical path:
+1. operator runs `/project <repo_url>`
+2. preview shows resolved repo + onboarding choices
+3. operator confirms
+4. ASM bridges into register / tracker-link / index flow
 
-## 9) Quick start for Paperclip
+Relevant areas in the repo include:
+- project registry
+- onboarding command flows
+- background indexing hooks
+- lineage-aware retrieval tests
 
-If your goal is to let **Paperclip** consume the same memory core:
+---
 
-### Build the Paperclip target
-```bash
-npm install
-npm run build:paperclip
-npm run package:paperclip
-npm run pack:paperclip
-```
+## 7) Capability overview
 
-### What Paperclip consumes
-Paperclip should consume:
-- shared core contracts/use-cases
-- Paperclip adapter runtime
-- no OpenClaw plugin metadata/runtime dependency unless explicitly needed
+### Memory capabilities
+- `memory_search`
+- `memory_store`
+- `memory_slot_get`
+- `memory_slot_set`
+- `memory_slot_delete`
+- `memory_slot_list`
+- `memory_graph_*`
 
-### Current maturity
-Paperclip path has:
-- adapter contracts
-- compatibility mapper
-- runtime wrapper
-- production-like smoke verification
+### Project capabilities
+- project register / list / inspect flows
+- project tracker linking
+- project indexing / reindexing
+- lifecycle-aware retrieval gating
+- hybrid lineage context retrieval
 
-But README intentionally does **not** overclaim this as full production-grade multi-runtime completion.
+### Platform/operations capabilities
+- shared config bootstrap
+- OpenClaw install flow
+- Paperclip install flow
+- OpenCode install flow
+- build/package/publish targets
 
 ---
 
-## 10) Build targets
+## 8) Build targets
 
 ### Default build
 ```bash
 npm run build
 ```
 
-Default build remains **OpenClaw-compatible** for backward compatibility.
-
 ### Explicit targets
 ```bash
 npm run build:openclaw
@@ -390,141 +287,78 @@ npm run pack:paperclip
 npm run pack:core
 ```
 
-### Publish targets
-```bash
-npm run publish:openclaw
-npm run publish:paperclip
-npm run publish:core
-```
-
-> Publish requires valid npm authentication. If `NPM_TOKEN` is missing, publish should be treated as not ready / dry-run only.
-
 ---
 
-## 11) CI/CD model
-
-GitHub Actions workflow: `.github/workflows/publish.yml`
-
-Current flow:
-- matrix build for `openclaw`, `paperclip`, `core`
-- build → package → pack `.tgz` → upload artifact
-- target-aware tests
-- `workflow_dispatch` for manual publish
-- `dry_run` supported
-- real publish gated by `NPM_TOKEN`
+## 9) Verification
 
-### Important distinction
-A `work/...` branch is for:
-- CI checks
-- PR review
-- dry-run readiness
-
-It is **not** the same as:
-- production deploy
-- final release approval
-- final npm publish approval
-
-Recommended flow:
-
-```text
-work/... push -> CI checks -> PR review -> approve -> merge default branch -> publish/release/deploy
+### CLI / installer verification
+```bash
+npm run test:asm-cli
+npx tsx tests/test-init-openclaw.ts
 ```
 
----
-
-## 12) Configuration notes
-
-### Embedding backend mapping
-When `embedBackend` is set:
-- `ollama` → `/api/embeddings`
-- `docker` → `/engines/llama.cpp/v1/embeddings`
-- `openai` → `/v1/embeddings`
-
-If omitted, legacy auto behavior is preserved.
-
-### SlotDB path resolution
-Resolution order:
-1. `OPENCLAW_SLOTDB_DIR`
-2. plugin config `slotDbDir`
-3. `${OPENCLAW_STATE_DIR}/agent-memo`
-
----
-
-## 13) Verification levels
-
-### Build level
-Confirms code compiles:
-
+### OpenClaw verification
 ```bash
-npm run build
-npm run build:all
+npm run test:openclaw
+npm run build:openclaw
 ```
 
-### Contract / integration level
+### Paperclip verification
 ```bash
-npm test
-npm run test:openclaw
 npm run test:paperclip
+npm run build:paperclip
 ```
 
 ### Project-aware targeted verification
 ```bash
 npx tsx tests/test-project-registry.ts
-npx tsx tests/test-project-reindex-diff.ts
 npx tsx tests/test-project-hybrid-lineage.ts
-npx tsx tests/test-project-legacy-backfill.ts
 ```
 
-### Production-like runtime verification
-Examples already added in this repo include:
-- Paperclip runtime E2E
-- OpenClaw anti-regression integration
-- production-like smoke parity harness
-
 ---
 
-## 14) Repository layout (high level)
+## 10) Repository layout
 
 ```text
 src/
+  adapters/
+    openclaw/
+    paperclip/
   core/
     contracts/
     usecases/
     ingest/
-  adapters/
-    openclaw/
-    paperclip/
-  tools/
+  db/
   hooks/
-  entries/
   services/
-  db/
   shared/
+  tools/
 
+bin/
 scripts/
+docs/
 artifacts/
-docs/architecture/
+tests/
 ```
 
 ---
 
-## 15) Current mental model
+## 11) Current positioning
 
-If you only remember one thing, remember this:
+A good public-facing description for this repo is:
 
-> **ASM v5.1 is a super memory platform for agents: conversation memory + project memory + retrieval/control-plane capabilities.**
+> **Agent Smart Memo is a project-aware super memory platform for coding agents, shipped as one package with CLI-first installation for OpenClaw, Paperclip, and OpenCode.**
 
 It helps agents:
-- remember ongoing runtime/conversation context
-- store/retrieve structured and semantic knowledge
-- register and map projects
+- remember conversation/runtime state
+- store and retrieve structured + semantic knowledge
+- onboard and map projects
 - index and reindex repos
-- retrieve engineering context with lineage
-- onboard projects with operator-friendly flows
-- bootstrap OpenClaw faster through the CLI
+- assemble better engineering context
+- reuse one shared config and one shared memory core across runtimes
 
 ---
 
-## 16) License
+## 12) License
 
 MIT © [mrc2204](https://github.com/cong91)