@mrc2204/agent-smart-memo 4.1.3 → 5.0.1

package/README.md

@@ -1,38 +1,265 @@
-# @mrc2204/agent-smart-memo
+# Agent Smart Memo
 
-🧠 **Smart Memory Plugin for [OpenClaw](https://openclaw.ai)** — Give your AI agents persistent, intelligent memory.
+> **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.
 
-Your agents forget everything after each conversation. This plugin fixes that.
+Originally built as an OpenClaw memory plugin for conversation/runtime memory, `agent-smart-memo` has evolved into a broader **agent memory platform**:
 
-## What it does
+- **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:
+
+- a **super memory layer** for agents
+- a **project-aware engineering memory system**
+- an **operator-friendly onboarding/runtime package**
+
+It is no longer accurate to describe ASM as only a small conversation-memory plugin.
+
+---
+
+## 1) What ASM v5.1 is
+
+ASM v5.1 combines two big memory domains.
+
+### 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
 
-- **Auto-Capture** — Automatically extracts important facts from every conversation (names, preferences, decisions, project status, etc.)
-- **Auto-Recall** — Injects relevant memories into agent context before each response — agents "remember" without being told
-- **Essence Distillation** — Filters noise, keeps only decision-grade facts. Your agent's memory stays clean and useful
-- **Slot Memory** — Structured key-value storage organized by categories (profile, preferences, project, environment)
-- **Vector Search** — Find semantically similar memories using Qdrant
-- **Multi-Agent Support** — Each agent maintains its own memory scope, no cross-contamination
+### B. Project memory
+Used for engineering/project-aware workflows:
+- project registry and aliasing
+- 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
 
-## Installation
+That is why ASM now acts as:
 
+> **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:
+- semantic recall
+- lexical/project filters
+- file/symbol/task context
+- parent/related/touched lineage context
+
+### Operator onboarding
+Operators can onboard a project with repo + alias + Jira mapping + optional index trigger using project-aware command flows.
+
+### Setup CLI
+OpenClaw setup is now easier through the global CLI:
+- `asm setup-openclaw`
+- `asm setup openclaw`
+- legacy-compatible `npm run init-openclaw`
+
+---
+
+## 3) Scope of this repository
+
+This repository now spans multiple practical layers.
+
+### OpenClaw runtime/plugin layer
+Includes:
+- plugin entry
+- tool registration
+- runtime hooks
+- OpenClaw packaging/build flow
+- setup/bootstrap CLI flow
+
+### 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
+
+Artifact intent:
+- **runtime-agnostic shared memory core**
+
+---
+
+## 5) Main capability areas
+
+### 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
+
+### 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
+
+---
+
+## 6) CLI / setup UX
+
+The preferred setup path is the global CLI.
+
+### Install globally
 ```bash
-openclaw plugins install @mrc2204/agent-smart-memo
+npm install -g @mrc2204/agent-smart-memo
 ```
 
-## Quick Start
+### Preferred setup flow
+```bash
+asm setup-openclaw
+```
 
-### 1. Prerequisites
+Also supported:
+```bash
+asm setup openclaw
+```
 
-You need two services running:
+Legacy-compatible flow:
+```bash
+npm run init-openclaw
+```
+
+### 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
 
-| Service | What for | Install |
-|---------|----------|---------|
-| [Qdrant](https://qdrant.tech/documentation/quick-start/) | Stores memory vectors | `docker run -d -p 6333:6333 qdrant/qdrant` |
-| [Ollama](https://ollama.ai) | Generates text embeddings | [Download](https://ollama.ai/download) then `ollama pull mxbai-embed-large` |
+This is the fastest path for operators who want ASM enabled in OpenClaw without manual config editing first.
 
-### 2. Configure
+---
 
-Add to your `~/.openclaw/openclaw.json`:
+## 7) Quick start for OpenClaw
+
+If your current goal is still “install and run ASM in OpenClaw”, use this section.
+
+### Install plugin directly
+```bash
+openclaw plugins install @mrc2204/agent-smart-memo
+```
+
+### Or install locally from source
+```bash
+npm install
+npm run build
+openclaw plugins install -l .
+```
+
+### 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
 {
@@ -45,25 +272,20 @@ Add to your `~/.openclaw/openclaw.json`:
       "agent-smart-memo": {
         enabled: true,
         config: {
-          // Required: Qdrant connection
           qdrantHost: "localhost",
           qdrantPort: 6333,
           qdrantCollection: "openclaw_memory",
 
-          // Required: Any OpenAI-compatible API for fact extraction
           llmBaseUrl: "https://api.openai.com/v1",
           llmApiKey: "sk-...",
           llmModel: "gpt-4o-mini",
 
-          // Required: Embedding backend (additive, backward-compatible)
           embedBaseUrl: "http://localhost:11434",
-          embedBackend: "ollama", // optional: ollama | openai | docker
-          embedModel: "mxbai-embed-large",
+          embedBackend: "ollama",
+          embedModel: "qwen3-embedding:0.6b",
           embedDimensions: 1024,
 
-          // Optional: explicit SlotDB target dir
-          // Priority: OPENCLAW_SLOTDB_DIR > config.slotDbDir > ${OPENCLAW_STATE_DIR}/agent-memo
-          slotDbDir: "/Users/mrcagents/.openclaw/agent-memo"
+          slotDbDir: "/Users/your-user/.openclaw/agent-memo"
         }
       }
     }
@@ -71,156 +293,238 @@ Add to your `~/.openclaw/openclaw.json`:
 }
 ```
 
-### 3. Done!
-
-Start chatting with your agent. Memories are captured automatically.
+---
 
-### Embedding backend mapping (internal)
+## 8) Project onboarding flow
 
-When `embedBackend` is set, runtime maps requests internally (no user-facing `embedPath` config):
+For project-aware onboarding in OpenClaw/Telegram flows, the current slash command is:
 
-- `ollama` → `/api/embeddings` body `{ model, prompt }` (legacy path/payload)
-- `docker` → `/engines/llama.cpp/v1/embeddings` body `{ model, input }`
-- `openai` → `/v1/embeddings` body `{ model, input }`
-
-If `embedBackend` is omitted, plugin preserves legacy auto behavior.
+```text
+/project <repo_url>
+```
 
-## Configuration Options
+### 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`
+
+---
+
+## 9) Quick start for Paperclip
+
+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
+```
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `qdrantHost` | string | `"localhost"` | Qdrant server hostname |
-| `qdrantPort` | number | `6333` | Qdrant server port |
-| `qdrantCollection` | string | `"openclaw_memory"` | Qdrant collection name |
-| `llmBaseUrl` | string | — | OpenAI-compatible API base URL |
-| `llmApiKey` | string | — | API key for the LLM |
-| `llmModel` | string | `"gpt-4o-mini"` | Model for fact extraction |
-| `embedBaseUrl` | string | `"http://localhost:11434"` | Embedding service base URL |
-| `embedBackend` | string | _unset_ | Optional backend selector: `ollama` \| `openai` \| `docker` (unset = legacy auto behavior) |
-| `embedModel` | string | `"mxbai-embed-large"` | Embedding model name |
-| `embedDimensions` | number | `1024` | Embedding vector dimensions |
-| `slotDbDir` | string | `${OPENCLAW_STATE_DIR}/agent-memo` | Explicit SlotDB directory. Overridden by `OPENCLAW_SLOTDB_DIR` if set |
-| `autoCaptureEnabled` | boolean | `true` | Enable automatic fact extraction |
-| `autoCaptureMinConfidence` | number | `0.7` | Minimum confidence to store a fact (0-1) |
-| `contextWindowMaxTokens` | number | `12000` | Max tokens sent to LLM for extraction |
-| `summarizeEveryActions` | number | `6` | Auto-summarize project state every N turns |
-| `slotCategories` | string[] | `["profile","preferences","project","environment","custom"]` | Allowed slot categories |
-| `maxSlots` | number | `500` | Max slots per agent+user scope |
-| `injectStateTokenBudget` | number | `500` | Max tokens for auto-recall context injection |
+### What Paperclip consumes
+Paperclip should consume:
+- shared core contracts/use-cases
+- Paperclip adapter runtime
+- no OpenClaw plugin metadata/runtime dependency unless explicitly needed
 
-See [CONFIG.example.json](./CONFIG.example.json) for a copy-paste template.
+### Current maturity
+Paperclip path has:
+- adapter contracts
+- compatibility mapper
+- runtime wrapper
+- production-like smoke verification
 
-### SlotDB Path Resolution
+But README intentionally does **not** overclaim this as full production-grade multi-runtime completion.
 
-`agent-smart-memo` now resolves the SQLite slot database directory in this order:
+---
 
-1. `OPENCLAW_SLOTDB_DIR`
-2. Plugin config `slotDbDir`
-3. Legacy fallback `${OPENCLAW_STATE_DIR}/agent-memo`
+## 10) Build targets
 
-Examples:
+### Default build
+```bash
+npm run build
+```
 
-- `OPENCLAW_SLOTDB_DIR=/Users/mrcagents/.openclaw/agent-memo` → DB file becomes `/Users/mrcagents/.openclaw/agent-memo/slots.db`
-- Legacy `new SlotDB("/Users/mrcagents/.openclaw")` still resolves to `/Users/mrcagents/.openclaw/agent-memo/slots.db`
-- Passing `/Users/mrcagents/.openclaw/agent-memo` as the target dir will **not** create nested `/agent-memo/agent-memo`
+Default build remains **OpenClaw-compatible** for backward compatibility.
 
+### Explicit targets
+```bash
+npm run build:openclaw
+npm run build:paperclip
+npm run build:core
+npm run build:all
+```
 
-## How It Works
+### Packaging
+```bash
+npm run package:openclaw
+npm run package:paperclip
+npm run package:core
+```
 
+### Pack tarballs
+```bash
+npm run pack:openclaw
+npm run pack:paperclip
+npm run pack:core
 ```
-User sends message → Agent responds
-                          ↓
-                    [agent_end event]
-                          ↓
-              Auto-Capture extracts facts
-              using LLM + Essence Distillation
-                          ↓
-              Facts stored in SlotDB + Qdrant
-                          ↓
-              Next conversation starts
-                          ↓
-              Auto-Recall searches relevant memories
-                          ↓
-              Context injected into agent prompt
-                          ↓
-              Agent "remembers" previous conversations ✨
+
+### Publish targets
+```bash
+npm run publish:openclaw
+npm run publish:paperclip
+npm run publish:core
 ```
 
-### Essence Distillation Modes
+> Publish requires valid npm authentication. If `NPM_TOKEN` is missing, publish should be treated as not ready / dry-run only.
 
-The plugin automatically detects what kind of content is being discussed and applies the right distillation mode:
+---
 
-| Mode | Auto-detected when... | What it keeps |
-|------|----------------------|---------------|
-| `general` | Most conversations | Key decisions, rules, configurations |
-| `principles` | Learning or teaching content | Core principles, atomic rules |
-| `requirements` | Technical specs or constraints | Measurable requirements, acceptance criteria |
-| `market_signal` | Financial or market discussions | Actionable signals, risk levels, triggers |
+## 11) CI/CD model
 
-Modes are inferred automatically — no configuration needed.
+GitHub Actions workflow: `.github/workflows/publish.yml`
 
-## Available Tools
+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`
 
-These tools are automatically registered and available to your agents:
+### Important distinction
+A `work/...` branch is for:
+- CI checks
+- PR review
+- dry-run readiness
 
-| Tool | Description |
-|------|-------------|
-| `memory_search` | Semantic search across all stored memories |
-| `memory_store` | Manually store a memory with vector embedding |
-| `memory_auto_capture` | Manually trigger fact extraction on text |
-| `memory_slot_get` | Read slot value(s) by key or category |
-| `memory_slot_set` | Write a structured slot value |
-| `memory_slot_delete` | Remove a slot |
-| `memory_slot_list` | List all slots for current scope |
-| `memory_graph_add` | Add a knowledge graph relation |
-| `memory_graph_query` | Query the knowledge graph |
+It is **not** the same as:
+- production deploy
+- final release approval
+- final npm publish approval
 
-## LLM Compatibility
+Recommended flow:
 
-Any OpenAI-compatible chat completions API works:
+```text
+work/... push -> CI checks -> PR review -> approve -> merge default branch -> publish/release/deploy
+```
 
-| Provider | `llmBaseUrl` | `llmModel` |
-|----------|-------------|------------|
-| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
-| Anthropic (via proxy) | Your proxy URL | `claude-sonnet-4-20250514` |
-| Local (Ollama) | `http://localhost:11434/v1` | `llama3.2` |
-| OpenRouter | `https://openrouter.ai/api/v1` | `google/gemini-2.5-flash` |
-| Any proxy | Your proxy URL | Your model |
+---
 
-## Commands
+## 12) Configuration notes
 
-```bash
-# Install
-openclaw plugins install @mrc2204/agent-smart-memo
+### Embedding backend mapping
+When `embedBackend` is set:
+- `ollama` → `/api/embeddings`
+- `docker` → `/engines/llama.cpp/v1/embeddings`
+- `openai` → `/v1/embeddings`
 
-# Update to latest version
-openclaw plugins update agent-smart-memo
+If omitted, legacy auto behavior is preserved.
 
-# Check status
-openclaw plugins info agent-smart-memo
+### SlotDB path resolution
+Resolution order:
+1. `OPENCLAW_SLOTDB_DIR`
+2. plugin config `slotDbDir`
+3. `${OPENCLAW_STATE_DIR}/agent-memo`
 
-# Uninstall
-openclaw plugins uninstall agent-smart-memo
-```
+---
 
-## Development
+## 13) Verification levels
 
-```bash
-# Clone
-git clone https://github.com/cong91/agent-smart-memo.git
-cd agent-smart-memo
+### Build level
+Confirms code compiles:
 
-# Install & build
-npm install
+```bash
 npm run build
+npm run build:all
+```
 
-# Link for local development (changes apply immediately)
-openclaw plugins install -l .
-
-# Run tests
+### Contract / integration level
+```bash
 npm test
+npm run test:openclaw
+npm run test: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
 ```
 
-## License
+### 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)
+
+```text
+src/
+  core/
+    contracts/
+    usecases/
+    ingest/
+  adapters/
+    openclaw/
+    paperclip/
+  tools/
+  hooks/
+  entries/
+  services/
+  db/
+  shared/
+
+scripts/
+artifacts/
+docs/architecture/
+```
+
+---
+
+## 15) Current mental model
+
+If you only remember one thing, remember this:
+
+> **ASM v5.1 is a super memory platform for agents: conversation memory + project memory + retrieval/control-plane capabilities.**
+
+It helps agents:
+- remember ongoing runtime/conversation context
+- store/retrieve structured and semantic knowledge
+- register and map projects
+- index and reindex repos
+- retrieve engineering context with lineage
+- onboard projects with operator-friendly flows
+- bootstrap OpenClaw faster through the CLI
+
+---
+
+## 16) License
 
 MIT © [mrc2204](https://github.com/cong91)

package/dist/adapters/openclaw/tool-runtime.d.ts

@@ -0,0 +1,29 @@
+import { SlotDB } from "../../db/slot-db.js";
+import type { MemoryUseCasePort } from "../../core/contracts/adapter-contracts.js";
+import type { SemanticMemoryUseCase } from "../../core/usecases/semantic-memory-usecase.js";
+import { type MemoryRuntimeConfig } from "../../core/runtime-boundary.js";
+export declare function configureOpenClawRuntime(options?: {
+    stateDir?: string;
+    slotDbDir?: string;
+    semanticUseCaseFactory?: (slotDbDir: string) => SemanticMemoryUseCase | undefined;
+}): MemoryRuntimeConfig;
+export declare function getSessionKey(ctx: any): string;
+export declare function parseOpenClawSessionIdentity(sessionKey: string): {
+    userId: string;
+    agentId: string;
+};
+export declare function getSlotDBForContext(ctx: any): SlotDB;
+export declare function getMemoryUseCasePortForContext(ctx: any): MemoryUseCasePort;
+export declare function createOpenClawResult(text: string, isError?: boolean): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        toolResult: {
+            text: string;
+        };
+    };
+    isError: boolean;
+};
+//# sourceMappingURL=tool-runtime.d.ts.map