memorix 1.2.10 → 1.3.0

package/docs/1.3-MEMORY-ARCHITECTURE.md

@@ -0,0 +1,236 @@
+# Memorix 1.3: Memory Architecture 2.0
+
+## Problem
+
+Memorix already captures useful project observations, code-state evidence,
+knowledge claims, wiki pages, workflows, sessions, and compaction checkpoints.
+Those records have different sources and lifecycles, but they are not yet
+expressed as one cognitive memory architecture. In particular, a `personal`
+observation still lives under one project and cannot safely become durable
+cross-project knowledge for the local user.
+
+Version 1.3 makes Memorix a local-first persistent memory system for coding
+agents. It does not replace the agent's context window or turn every note into
+a global profile. It supplies small, current, source-aware working context and
+keeps durable knowledge under explicit lifecycle control.
+
+## Goals
+
+1. Model durable memory with independent **kind**, **scope**, **state**, and
+   **evidence** dimensions.
+2. Add local-user durable memories that can be reused across projects without
+   silently exposing project facts to unrelated projects.
+3. Treat the existing Task Workset as derived working memory, not another
+   database or a transcript dump.
+4. Allow agents to capture a candidate through their normal memory write path,
+   while keeping qualification and approval explicit and inspectable through
+   the CLI.
+5. Include only bounded, task-relevant qualified or approved durable memory in
+   project context. A candidate, stale record, or unrelated user preference is
+   never injected merely because it exists.
+6. Preserve all existing Observation, Claim, Wiki, Workflow, Session, and
+   Code Memory behavior. The migration is additive and idempotent.
+
+## Non-goals
+
+- No cloud account, remote synchronization, organization directory, or
+  cross-machine identity system in 1.3.
+- No automatic export of source code, paths, Git facts, or project observations
+  into a user-global memory.
+- No claim that a graph alone makes information true. Graph links remain
+  navigational provenance, and source evidence remains authoritative.
+- No automatic execution of a stored procedure. Procedures advise a Workset;
+  existing workflow gates still control execution and verification.
+- No automated psychological profile or covert user tracking.
+
+## Mental Model
+
+The following axes are deliberately independent.
+
+| Axis | Values | Meaning |
+| --- | --- | --- |
+| Cognitive kind | `episodic`, `semantic`, `procedural` | What the durable item represents. |
+| Scope | `project`, `user`, `team` | Who may retrieve it and where it may travel. |
+| State | `candidate`, `qualified`, `approved`, `archived`, `superseded` | Whether it can be delivered and how much trust it carries. |
+| Source | `manual`, `agent`, `hook`, `git`, `test`, `code-state`, `workflow` | Where the supporting evidence came from. |
+| Portability | `project-bound`, `portable` | Whether a user item may be considered outside its origin project. |
+
+Working memory is not a fourth persisted record class. It is the temporary
+Task Workset assembled for one task from current code facts, continuation
+evidence, source-qualified knowledge, and relevant durable memories under a
+strict token budget.
+
+### Kinds
+
+- **Episodic**: a bounded event or handoff, such as a completed debugging
+  session and its verified result. Existing Sessions and compaction checkpoints
+  remain the canonical event sources.
+- **Semantic**: a source-backed fact, preference, or stable convention. Existing
+  Claims and reviewed Wiki pages remain project semantic truth; new long-term
+  memories cover deliberate user-scoped facts and portable conventions.
+- **Procedural**: a reusable way of working with applicability and verification
+  evidence. Existing canonical Workflows and Mini-Skills remain the project
+  procedure sources; the long-term layer can hold deliberately promoted user
+  procedures.
+
+## Canonical Storage
+
+1. `observations` remains the raw evidence ledger and legacy-compatible agent
+   write surface.
+2. `knowledge_claims`, Markdown Wiki pages, Workflows, Sessions, Code Graph
+   snapshots, and checkpoints remain their existing specialized stores.
+3. A new SQLite `long_term_memories` table stores curated cross-source memory
+   artifacts. Each item records its origin project, owner, scope, cognitive
+   kind, lifecycle state, evidence references, tags, and portability.
+4. A local installation identity is stored only on the local machine. It is a
+   random stable identifier unless `MEMORIX_USER_ID` is explicitly supplied.
+   It is never derived from a model prompt and is never transmitted by
+   Memorix.
+
+The new table does not copy all legacy observations on upgrade. Existing
+records keep their current behavior. Promotion creates a new artifact with
+references to its evidence, so no provenance is lost and no historical record
+becomes global by accident.
+
+## Lifecycle and Promotion
+
+```text
+raw observation / session / claim / workflow result
+                 |
+                 v
+          long-term candidate
+                 |
+          explicit qualify
+                 v
+      qualified durable memory
+                 |
+     explicit approval or review
+                 v
+       approved durable memory
+                 |
+       archive / supersede
+```
+
+- Agent-facing `memorix_store` may create an **additional candidate** when a
+  caller explicitly requests long-term capture. It always writes normal source
+  evidence first.
+- Candidate artifacts are visible to management commands but are excluded from
+  automatic task context.
+- Qualification requires at least one evidence reference. A semantic or
+  procedural item never becomes an unsupported text summary.
+- Approval is a separate deliberate operation. The CLI records the transition
+  and reason in the artifact audit trail.
+- Project code, Git, observation, test, and workflow evidence may support a
+  project-bound item. A portable user item rejects project-bound source kinds;
+  the operator must create it from user/manual evidence instead.
+
+## Scope and Privacy Rules
+
+| Scope | Default retrieval | Cross-project behavior |
+| --- | --- | --- |
+| `project` | Current project only | Never crosses automatically. |
+| `user` + `project-bound` | Origin project for the same local user | Does not cross. |
+| `user` + `portable` | Same local user, task-relevant only | May cross projects after explicit portable promotion. |
+| `team` | Explicit active project team only | Not cross-project in 1.3. |
+
+`personal` Observation visibility remains a project-local private sharing rule
+for backward compatibility. It is not renamed to `user`: a project-private
+observation and a user-level portable durable memory are intentionally
+different things.
+
+## Retrieval and Delivery
+
+Task Workset assembly combines existing project facts with a new long-term
+selection stage:
+
+1. Filter by owner, scope, project, portability, lifecycle state, and reader
+   capability before ranking.
+2. Rank only approved or qualified artifacts by task term overlap, kind fit,
+   validation recency, and explicit tag matches. If that produces no result
+   and the user has configured an embedding provider, one bounded semantic
+   fallback may compare the task with already-visible durable records. A slow,
+   unavailable, or disabled provider falls back to keyword-only retrieval.
+3. Include at most three short entries under a fixed sub-budget. Include title,
+   kind, scope, applicability, and a `durable:<id>` provenance reference, not
+   a long historical narrative. An agent can open that reference through the
+   existing `memorix_detail` route when it needs the full evidence-backed
+   record.
+4. Keep current code, dirty-worktree cautions, source-backed claims, and
+   verification evidence ahead of optional durable enrichment.
+5. Record selected and omitted durable memory in the delivery receipt without
+   exposing private content in diagnostics.
+
+The result is a useful memory directory for an agent, not an automatic history
+dump. An agent can request detail through the CLI when it needs more.
+
+### Semantic fallback budget
+
+Keyword matching is the deterministic first route. Only when no eligible long-term
+record matches may Memorix use the configured embedding provider for a small,
+scope-filtered semantic fallback. It has a strict 1.8-second request budget and
+no retry. Provider startup probing receives the same budget. Failure is silent
+from the agent's point of view: the normal lexical Workset is still delivered.
+This keeps semantic recall additive rather than making a remote API a dependency
+of task continuation.
+
+## Operator Surface
+
+The CLI is the complete management surface:
+
+```text
+memorix memory long-term list
+memorix memory long-term show --id <id>
+memorix memory long-term add --kind procedural --scope user --portability portable --title "Release verification preference" --text "Run focused tests and a packed-package smoke before publishing." --tags "release,verification" --applicability "When publishing an npm package."
+memorix memory long-term promote --from-observation <id> --kind semantic --scope project
+memorix memory long-term qualify --id <id> --reason "verified against focused test"
+memorix memory long-term approve --id <id> --reason "reviewed by operator"
+memorix memory long-term archive --id <id> --reason "no longer current"
+memorix memory long-term supersede --id <old-id> --superseded-by <qualified-id> --reason "replaced by the current procedure"
+```
+
+`memorix_store` gains optional long-term capture metadata for agents. This
+keeps the default MCP micro profile small: no additional MCP tool is necessary
+to capture a candidate or receive relevant working context. The CLI remains the
+inspection, promotion, and audit route.
+
+## Compatibility and Migration
+
+- SQLite creates the new table and indexes through an idempotent named schema
+  migration.
+- Existing records receive no data rewrite and remain project-visible under
+  their current legacy rules.
+- Missing local user identity means no user-memory retrieval; a write creates
+  the local identity lazily.
+- The new APIs fail closed for unavailable owner/team context. They never
+  broaden project visibility to compensate for missing identity.
+
+## Acceptance Criteria
+
+1. A normal Observation remains readable after the migration with unchanged
+   visibility and project behavior.
+2. A promoted project semantic memory appears in a task Workset only after
+   qualification.
+3. A portable user semantic memory created under one project can be selected in
+   another local project for the same owner, while a project-bound user memory
+   cannot.
+4. A portable promotion with code, Git, observation, test, or workflow source
+   evidence is rejected.
+5. Team memories are absent without explicit active team membership.
+6. Candidate, archived, superseded, and unrelated durable memories do not
+   appear in the agent-facing prompt.
+7. The Workset stays within its configured token budget and its receipt records
+   durable memory selection or omission.
+8. CLI JSON flows cover create, list, promote, qualify, approve, archive, and
+   cross-project retrieval.
+9. Type checking, focused tests, full test suite, package build, and an
+   installed-package CLI smoke all pass before publishing 1.3.0.
+
+## Research Basis
+
+This design uses the memory taxonomy and evidence discipline in
+`AI-Agents-in-Depth` (working / episodic / semantic / procedural memory), while
+keeping Memorix's current-source-first code-memory and proposal-first Knowledge
+Workspace principles. It takes AgentMemory's capture/consolidate/forget and
+token-budget lessons as inspiration, but does not adopt generic time-decay or
+automatic global slots for code facts. Source-qualified promotion and explicit
+portable scope are the safety boundary for a coding-agent memory system.

package/docs/AGENT_OPERATOR_PLAYBOOK.md

@@ -50,12 +50,14 @@ For the 1.2 release line, the visible product shape is:
 
 ### CLI is the direct command surface; MCP is the integration layer
 
-For direct use, prefer `memorix ...` commands first. In the 1.2 line, the CLI covers session, memory, Code State, knowledge workspaces, reasoning, retention, formation, audit, transfer, skills, orchestration coordination, sync, ingest workflows, and the bundled terminal agent.
+For direct use, prefer `memorix ...` commands first. In the 1.3 line, the CLI covers session, memory, reviewed long-term memory, Code State, knowledge workspaces, reasoning, retention, formation, audit, transfer, skills, orchestration coordination, sync, ingest workflows, and the bundled terminal agent.
 
 Do not ask memory-only users to join coordination state. A lightweight session is enough for memory, retrieval, reasoning, and continuation. Use `joinTeam` / `team_manage(join)` only for explicit task/message/lock coordination or for CLI-agent work managed by `memorix orchestrate`.
 
 An unbound terminal is intentionally project-scoped: it reads and writes project-visible memory only. Use `memorix identity join --agent-type <agent>` or `memorix identity use --agent-id <id>` only when an operator explicitly needs personal/team memory or coordinated task actions. `memorix identity clear` removes that local selection; `--as <agent-id>` is the one-command script form and still requires an active member of the current project.
 
+Long-term memory is a reviewed layer, not a generic global note store. `memorix memory long-term add` creates a candidate; `qualify` and `approve` are explicit audit transitions before it can appear in a bounded task Workset. A project-derived observation, code fact, Git fact, test, session, Claim, or workflow stays project-bound. Only manual or user-confirmed `user + portable` records can cross local projects for the same local installation identity. When one is task-matched in a Workset, it is intentionally usable background even if its origin differs; use its `durable:<id>` reference with `memorix_detail` only when the full record is needed. Use `archive` or `supersede` when a durable item is no longer current.
+
 `--cwd <git-project>` is the canonical way to run direct CLI work from outside a repository. It changes the command's project anchor only; Git remains the source of truth for final project identity.
 
 Use MCP when:

package/docs/API_REFERENCE.md

@@ -219,6 +219,7 @@ Important inputs:
 - optional `relatedCommits`
 - optional `relatedEntities`
 - optional `visibility`: `project` (default), `personal`, or `team`
+- optional `longTerm`: an explicit source-backed long-term candidate with `kind` (`episodic`, `semantic`, or `procedural`), an optional `scope` (`project`, `user`, or `team`), tags, and applicability
 
 Visibility controls who can retrieve a record through agent-facing memory
 tools. Normal memories default to `project`. `personal` and `team` writes
@@ -230,6 +231,13 @@ When the current Autopilot task is read-only or explicitly says not to modify
 files, `memorix_store` returns without writing. Use `overrideReadOnly: true`
 only when the user explicitly asks to preserve a record during that task.
 
+`longTerm` is deliberately opt-in. It stores the normal Observation first, then
+creates a separate candidate with an evidence reference. Candidates are not
+inserted into a Task Workset. Review them with `memorix memory long-term
+list|show|qualify|approve|archive|supersede`. Source-derived entries remain
+project-bound; only a manual or user-confirmed `user + portable` record created
+through the CLI may cross local projects for the same local installation.
+
 Example:
 
 ```json
@@ -291,7 +299,7 @@ Global example:
 
 ### `memorix_detail`
 
-Fetch full observation detail.
+Fetch full observation, mini-skill, or curated long-term memory detail.
 
 After `memorix_project_context`, use `purpose` only for a named missing fact. Set `force: true` only when the user explicitly asks for the full underlying record already represented in the brief.
 
@@ -299,6 +307,10 @@ Supports two modes:
 
 - `ids` for current-project observations
 - `refs` for project-aware cross-project lookup
+- `typedRefs` for typed observation/skill refs and a `durable:<uuid>` reference
+  emitted by a Task Workset. A matching `user + portable` durable item is
+  intentionally reusable across local projects, but remains background guidance
+  rather than a current-project fact.
 
 Examples:
 
@@ -316,6 +328,13 @@ Examples:
 }
 ```
 
+```json
+{
+  "typedRefs": ["durable:9f3d9a6d-1111-4222-8333-abcdefabcdef"],
+  "purpose": "Need the full verified release procedure before publishing."
+}
+```
+
 ### `memorix_timeline`
 
 Get the chronological context around one observation.

package/docs/ARCHITECTURE.md

@@ -2,11 +2,16 @@
 
 Memorix is an open-source cross-agent memory layer for coding agents via MCP.
 
-It combines three core memory layers:
+It combines three source-of-truth memory layers and a curated long-term memory layer:
 
 - **Observation Memory** for what changed and how things work
 - **Reasoning Memory** for why choices were made
 - **Git Memory** for engineering truth derived from commits
+- **Long-term Memory** for explicitly curated episodic, semantic, and procedural knowledge that should outlive a single project session
+
+Observation, reasoning, and Git records remain the canonical evidence. Long-term
+memory references that evidence and has its own lifecycle; it is not a second
+copy of every conversation or a global dump shared between unrelated projects.
 
 These layers are exposed through MCP tools, CLI workflows, and an HTTP service.
 
@@ -36,6 +41,7 @@ flowchart LR
         C2["Reasoning store"]
         C3["Git memory store"]
         C4["Session / team registry"]
+        C5["Curated long-term memory"]
     end
 
     subgraph Intelligence["Intelligence and Quality"]
@@ -65,6 +71,7 @@ flowchart LR
     B3 --> C2
     B3 --> C3
     B3 --> C4
+    B3 --> C5
 
     C1 --> D1
     C1 --> D2
@@ -74,6 +81,8 @@ flowchart LR
     C2 --> D3
     C3 --> D2
     C4 --> D3
+    C5 --> D4
+    C5 --> E1
 
     D1 --> E1
     D2 --> E1
@@ -114,6 +123,8 @@ Main pieces:
 - `src/memory/retention.ts`
 - `src/memory/graph.ts`
 - `src/memory/consolidation.ts`
+- `src/memory/long-term.ts`
+- `src/memory/long-term-store.ts`
 
 Responsibilities:
 
@@ -123,6 +134,8 @@ Responsibilities:
 - manage session state
 - retention, archive, and deduplication
 - knowledge graph entities and relations
+- curate long-lived episodes, facts, and procedures with source evidence,
+  qualification, approval, archival, and supersession
 
 ### Intelligence and Quality Layer
 
@@ -212,6 +225,26 @@ Git Memory turns commits into structured memory with source provenance:
 
 This creates an engineering truth layer that complements human- or agent-authored observations.
 
+### Curated Long-term Memory
+
+Long-term memory holds a deliberately small set of records that remain useful
+after a project session ends:
+
+- **episodic**: a completed, reusable episode
+- **semantic**: a stable fact or principle
+- **procedural**: a repeatable workflow
+
+It is separate from ordinary observations so the two jobs do not get confused:
+
+- an observation records what happened in context;
+- a long-term record says that the fact or procedure has earned durable reuse.
+
+Each record is source-bound, auditable, and moves through
+`candidate -> qualified -> approved -> archived/superseded`. Candidates are
+never injected into an agent context. A record can be portable only when it is
+user-owned and based on explicit manual or user evidence; project, team, Git,
+session, code, and claim evidence never crosses that boundary.
+
 ---
 
 ## 3. Main Data Flows

package/docs/DEVELOPMENT.md

@@ -13,9 +13,9 @@ Memorix is a TypeScript project built around:
 
 ## Current Development Baseline
 
-The current release work targets the **1.1 line** while package metadata may still show the last published patch version until the release commit is cut.
+The current release work targets the **1.3 line** while package metadata may still show the last published version until the release commit is cut.
 
-Contributors should assume the following areas are part of the 1.1 release line:
+Contributors should assume the following areas are part of the 1.3 release line:
 
 - shared memory across MCP clients, CLI, SDK, dashboard, hooks, and memcode
 - memcode uses Memorix project memory, hooks, `/memory` commands, resumable sessions, and model switching as the bundled terminal agent
@@ -26,6 +26,7 @@ Contributors should assume the following areas are part of the 1.1 release line:
 - notify-only auto-update by default with explicit install opt-in
 - dashboard config loading aligned with CLI/TUI status surfaces
 - the existing layered retrieval, retention, attribution, and compact output model
+- source-backed long-term memory with candidate, qualification, approval, archival, supersession, and explicit portable user scope
 
 ---
 

package/docs/MODULES.md

@@ -1,8 +1,12 @@
 # Memorix 模块详解
 
-> 最后更新: 2026-03-09 (v1.0.0)
+> 最后更新: 2026-07-30 (v1.3.0)
 > 本文档详细记录每个模块的实现细节、关键算法和注意事项
 
+> 本文档中的早期 JSON/Orama 章节保留为历史模块说明。当前运行时的
+> SQLite 数据层和长期记忆生命周期以 `docs/ARCHITECTURE.md`、
+> `docs/1.3-MEMORY-ARCHITECTURE.md` 及对应源码为准。
+
 ---
 
 ## 1. Orama 搜索引擎 (`store/orama-store.ts`)
@@ -148,6 +152,28 @@ Archive-candidate: age > 100% retention & !immune
 
 ---
 
+## 5. 长期记忆 (`memory/long-term.ts`, `memory/long-term-store.ts`)
+
+长期记忆不是把所有 observation 再复制一遍。它是由已有证据支撑、经过
+明确管理的少量长期知识，面向跨会话持续使用。
+
+| 维度 | 取值 | 含义 |
+|---|---|---|
+| 认知类型 | `episodic` / `semantic` / `procedural` | 完成经历、稳定事实、可复用流程 |
+| 范围 | `project` / `user` / `team` | 项目、同一安装的用户、显式团队 |
+| 生命周期 | `candidate` -> `qualified` -> `approved` -> `archived` / `superseded` | 候选不会自动注入；只有合格或已批准的记录才会进入受限 Workset |
+
+### 核心边界
+
+- 每条记录保存来源 observation 和生命周期事件，便于审计和追溯。
+- `portable` 只允许用户范围、并且来源是显式手工或用户输入的记录。
+- Git、代码、会话、项目、团队和模型生成的证据不能因为标记为长期记忆就跨项目共享。
+- 用户通过 `memorix memory long-term` 管理记录；MCP 的 `memorix_store`
+  只能创建候选，不会偷偷把日常对话升级成长期知识。
+- 检索遵守任务相关性和 token 预算，最多放入少量合格/批准记录，不回填完整历史。
+
+---
+
 ## 5. 实体抽取器 (`memory/entity-extractor.ts`)
 
 ### 正则模式

package/docs/README.md

@@ -32,6 +32,7 @@ The public docs are organized by user intent:
 | --- | --- |
 | CLI commands and MCP tools | [API_REFERENCE.md](API_REFERENCE.md) |
 | Memory Autopilot, Code State, and context packs | [API_REFERENCE.md § Memory Autopilot, Code State, and Context Packs](API_REFERENCE.md#memory-autopilot-code-state-and-context-packs), [1.2 Code State](1.2.0-CODE-STATE.md), and [1.2 Workset Retrieval](1.2.0-WORKSET-RETRIEVAL.md) |
+| Reviewed episodic, semantic, and procedural long-term memory | [1.3 Memory Architecture](1.3-MEMORY-ARCHITECTURE.md) |
 | Reviewable knowledge pages and workflow inheritance | [API_REFERENCE.md § Knowledge Workspace and Workflows](API_REFERENCE.md#knowledge-workspace-and-workflows), [1.2 Knowledge Workspace](1.2.0-KNOWLEDGE-WORKSPACE.md), and [1.2 Workflow Inheritance](1.2.0-WORKFLOW-INHERITANCE.md) |
 | Git-derived engineering memory | [GIT_MEMORY.md](GIT_MEMORY.md) |
 | Memory formation and quality pipeline | [MEMORY_FORMATION_PIPELINE.md](MEMORY_FORMATION_PIPELINE.md) |
@@ -87,6 +88,7 @@ The public docs are organized by user intent:
 | 1.2 task-shaped evidence selection | [1.2 Workset Retrieval](1.2.0-WORKSET-RETRIEVAL.md) |
 | 1.2 non-blocking refresh and maintenance contract | [1.2 Dynamic Lifecycle](1.2.0-DYNAMIC-LIFECYCLE.md) |
 | 1.2 honest Lite and optional semantic CodeGraph provider contract | [1.2 Provider Quality](1.2.0-PROVIDER-QUALITY.md) |
+| 1.3 long-term memory model, source boundary, and lifecycle | [1.3 Memory Architecture](1.3-MEMORY-ARCHITECTURE.md) |
 | Active context-control work | [1.2.2 Memory Control Plane](1.2.2-MEMORY-CONTROL-PLANE.md) |
 | Historical cloud sync and multi-agent research | [CLOUD_SYNC_AND_MULTI_AGENT_RESEARCH.md](CLOUD_SYNC_AND_MULTI_AGENT_RESEARCH.md) |
 | Known issues and old roadmap notes | [KNOWN_ISSUES_AND_ROADMAP.md](KNOWN_ISSUES_AND_ROADMAP.md) |
@@ -115,9 +117,7 @@ Historical/deep-reference documents may describe older designs. If they conflict
 
 ## Current Product Line
 
-The released product is on the **1.1 line**. Active 1.2 design work is tracked
-in the [1.2 Development Charter](1.2.0-DEVELOPMENT-CHARTER.md). The current
-released baseline has:
+The released product is on the **1.3 line**. The current baseline has:
 
 - `memorix setup --agent <agent> --global` is the default agent integration command
 - `memorix serve` is the manual stdio MCP server for external agents

package/docs/dev-log/progress.txt

@@ -364,3 +364,25 @@
   CLI `context --json` path returned a structured Workset. `npm pack --dry-run`
   and `npm publish --dry-run --ignore-scripts` both accepted the final tarball
   without manifest normalization warnings.
+
+## 1.3 Curated Long-Term Memory
+- Added an additive SQLite long-term-memory layer with explicit episodic,
+  semantic, and procedural kinds; independent scope and portability; source
+  evidence; and an auditable `candidate -> qualified -> approved ->
+  archived/superseded` lifecycle. Existing Observation, Claim, Wiki, Workflow,
+  Session, and Code State stores remain their own canonical sources.
+- Added the complete CLI lifecycle surface and extended the existing MCP store/
+  detail routes without increasing the default seven-tool micro profile. Task
+  Worksets expose at most three relevant approved or qualified records as short
+  `durable:<id>` references for progressive expansion.
+- Explicit `user + portable` manual/user-confirmed records can be reused across
+  local projects for the same owner. Code, Git, tests, sessions, workflows,
+  observations, claims, and team/project evidence remain project-bound.
+- Semantic durable retrieval is an optional cross-language/paraphrase fallback
+  after lexical selection. Provider initialization and the one batch request use
+  a 1.8-second no-retry budget; API request cancellation is propagated to the
+  remote fetch so an unavailable embedding service cannot retain a CLI process.
+- Verification in progress: focused lifecycle/CLI/MCP/embedding tests, a real
+  packed-package cross-project Chinese-to-English retrieval smoke, and an
+  isolated Claude Code plugin user test that returned the reviewed release
+  procedure without inspecting project files.

package/llms-full.txt

@@ -6,7 +6,7 @@ Memorix is a TypeScript/Node.js project that gives AI coding agents persistent,
 
 If you are an AI coding agent helping a user install, operate, or troubleshoot Memorix, read `docs/AGENT_OPERATOR_PLAYBOOK.md` before taking action. It is the main reference for install, runtime selection, Git/project binding, MCP integration, hooks, and troubleshooting.
 
-## 1.2 Multi-Dimensional Memory Model
+## 1.3 Multi-Dimensional Memory Model
 
 Memorix is not a transcript dump. The normal agent path is `memorix_project_context` or `memorix context --task "..."`, which assembles a bounded task Workset: current Git/package facts, selected observations and reasoning, Code State freshness, source-backed claims, matching knowledge/workflow starts, cautions, and verification hints.
 
@@ -15,6 +15,7 @@ Memorix is not a transcript dump. The normal agent path is `memorix_project_cont
 - **Claim Ledger** keeps provenance, confidence, conflicts, and lifecycle state separate from prose.
 - **Knowledge Workspace** compiles claims into reviewable Markdown proposals; it does not silently overwrite manually edited pages.
 - **Canonical Workflows** represent project process once and render conservative agent-specific adapters only on explicit request.
+- **Curated Long-Term Memory** keeps source-bound episodic, semantic, and procedural records separate from ordinary observations. A record is a candidate first, then can be explicitly qualified or approved; candidates, archived records, and superseded records never enter a Workset. A portable record is allowed only for explicit local `user + portable` knowledge with manual/user evidence. Project, team, Git, code, session, workflow, test, and observation evidence always remains project-bound. Keyword retrieval is primary; an optional semantic fallback is scope-filtered, limited to 1.8 seconds with no retry, and never blocks a lexical Workset when an embedding provider is slow or unavailable.
 - **Lifecycle maintenance** uses durable, resumable jobs so indexing, claim requalification, knowledge compile/lint, retention, and consolidation do not turn an interactive MCP request into a corpus-sized foreground job.
 
 The built-in CodeGraph Lite provider is a structural local fallback, not a complete semantic graph. If a project already has a healthy local CodeGraph index, `[codegraph].external_context = "auto"` can add a small validated semantic outline. Memorix never runs `codegraph init`, `index`, or `sync`, does not transmit the repository, and does not persist raw external code output.
@@ -111,6 +112,9 @@ Typical commands:
 ```bash
 memorix memory search --query "release blocker"
 memorix memory store --text "Auth tokens expire after 24h" --title "Auth token TTL" --entity auth --type decision
+memorix memory long-term add --kind procedural --scope user --portability portable --text "Always run focused tests before a patch release"
+memorix memory long-term qualify --id <memory-id> --reason "Verified in the release workflow"
+memorix memory long-term approve --id <memory-id> --reason "Approved for local reuse"
 memorix reasoning search --query "why sqlite"
 memorix session start --agent codex-main --agentType codex
 memorix receipt --json

package/llms.txt

@@ -25,6 +25,7 @@ Memorix combines durable memory with a bounded task Workset:
 - **Code State**: versioned local file/symbol/import facts and freshness links that keep memory tied to the current checkout
 - **Claim Ledger and Knowledge Workspace**: source-backed claims compiled into reviewable Markdown proposals, never silent overwrites
 - **Canonical Workflows**: project workflows with safe per-agent adapters and recorded verification outcomes
+- **Curated Long-Term Memory**: source-bound episodic, semantic, and procedural records that stay candidates until explicitly qualified or approved; only deliberately created `user + portable` records can be reused across projects on the same local installation. Keyword retrieval stays primary; optional cross-language/paraphrase fallback is bounded to 1.8 seconds and never blocks lexical delivery.
 
 For non-trivial coding work, agents normally call `memorix_project_context` (or `memorix context --task "...")`. It selects a small task Workset with current facts, relevant evidence, start files, cautions, and verification hints instead of dumping all old text memory. Search is project-scoped by default. Use global scope only when cross-project recall is intentional.
 
@@ -109,4 +110,5 @@ Endpoint: `http://localhost:3211/mcp`.
 - Git Memory: https://github.com/AVIDS2/memorix/blob/main/docs/GIT_MEMORY.md
 - memcode: https://github.com/AVIDS2/memorix/blob/main/docs/MEMCODE.md
 - Agent Playbook: https://github.com/AVIDS2/memorix/blob/main/docs/AGENT_OPERATOR_PLAYBOOK.md
+- Long-Term Memory Architecture: https://github.com/AVIDS2/memorix/blob/main/docs/1.3-MEMORY-ARCHITECTURE.md
 - Full AI context: https://github.com/AVIDS2/memorix/blob/main/llms-full.txt

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorix",
   "mcpName": "io.github.AVIDS2/memorix",
-  "version": "1.2.10",
+  "version": "1.3.0",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,
@@ -65,6 +65,7 @@
     "test:e2e": "vitest run tests/e2e/",
     "benchmark:codegraph": "node scripts/benchmark-codegraph-provider.cjs",
     "benchmark:retrieval": "npm run build && node scripts/benchmark-retrieval.mjs",
+    "generate:star-history": "node scripts/generate-star-history.mjs",
     "sync:mcp-registry": "node scripts/sync-mcp-registry-manifest.mjs",
     "check:mcp-registry": "node scripts/check-mcp-registry-manifest.mjs",
     "audit:pi-upstream": "node scripts/pi-upstream-audit.mjs",

package/plugins/antigravity/memorix/rules/memorix.md

@@ -9,6 +9,8 @@ Use Memorix when prior workspace context, decisions, fixes, or handoff state wou
 - Use `memorix_search` for focused lookup.
 - Use `memorix_detail` before relying on a specific memory.
 - Use `memorix_store` for durable workspace knowledge.
+- Use `longTerm` on `memorix_store` only for a stable fact, reusable procedure, or completed episode that merits explicit review. It creates a candidate, not live context; keep the default project scope and do not use it for routine updates.
+- A `user` + `portable` durable memory in a task brief is intentionally reusable across projects. When it matches the task, use it as background even if it originated elsewhere; it is not a current-project fact. Expand it only when needed with `memorix_detail` and `typedRefs: ["durable:<id>"]`, stating the missing fact as `purpose`.
 - Use `memorix_store_reasoning` for the reason behind a technical decision.
 - Use `memorix_resolve` when completed or outdated memories should stop surfacing.
 

package/plugins/claude/memorix/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "memorix",
-  "version": "1.2.10",
+  "version": "1.3.0",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/claude/memorix/skills/memorix-memory/SKILL.md

@@ -17,6 +17,7 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Need the full source for a search hit | `memorix_detail` | `memorix memory detail --id <id>` |
 | Need the sequence around one memory | `memorix_timeline` | `memorix memory timeline --id <id>` |
 | Learned reusable project knowledge | `memorix_store` | `memorix memory store --type <type> --entity <name> --title "<title>" "<text>"` |
+| Stable source-backed fact or procedure needing long-term review | `memorix_store` with `longTerm` | `memorix memory long-term qualify|approve --id <id> --reason "..."` |
 | Task or bug is complete/outdated | `memorix_resolve` | `memorix memory resolve --ids <ids>` |
 
 ## Search Rules
@@ -41,4 +42,6 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Accepted compromise | `trade-off` |
 
 - Use concise titles, stable entity names, relevant `filesModified`, and `topicKey` for evolving topics.
+- Use `longTerm` only for a stable fact, reusable procedure, or completed episode that merits explicit review. It creates a candidate, not live context; keep the default project scope and do not use it for routine updates.
+- A `user` + `portable` durable memory in a task brief is intentionally reusable across projects. When it matches the task, use it as background even if it originated elsewhere; it is not a current-project fact. Expand it only when needed with `memorix_detail` and `typedRefs: ["durable:<id>"]`, stating the missing fact as `purpose`.
 - Do not store secrets, credentials, raw private transcripts, trivial commands, or routine file reads.

package/plugins/codex/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.10",
+  "version": "1.3.0",
   "description": "Shared workspace memory for Codex and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codex/memorix/skills/memorix-memory/SKILL.md

@@ -18,6 +18,7 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Need the full source for a search hit | `memorix_detail` | `memorix memory detail --id <id>` |
 | Need the sequence around one memory | `memorix_timeline` | `memorix memory timeline --id <id>` |
 | Learned reusable project knowledge | `memorix_store` | `memorix memory store --type <type> --entity <name> --title "<title>" "<text>"` |
+| Stable source-backed fact or procedure needing long-term review | `memorix_store` with `longTerm` | `memorix memory long-term qualify|approve --id <id> --reason "..."` |
 | Task or bug is complete/outdated | `memorix_resolve` | `memorix memory resolve --ids <ids>` |
 
 ## Search Rules
@@ -42,4 +43,6 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Accepted compromise | `trade-off` |
 
 - Use concise titles, stable entity names, relevant `filesModified`, and `topicKey` for evolving topics.
+- Use `longTerm` only for a stable fact, reusable procedure, or completed episode that merits explicit review. It creates a candidate, not live context; keep the default project scope and do not use it for routine updates.
+- A `user` + `portable` durable memory in a task brief is intentionally reusable across projects. When it matches the task, use it as background even if it originated elsewhere; it is not a current-project fact. Expand it only when needed with `memorix_detail` and `typedRefs: ["durable:<id>"]`, stating the missing fact as `purpose`.
 - Do not store secrets, credentials, raw private transcripts, trivial commands, or routine file reads.

package/plugins/copilot/memorix/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.10",
+  "version": "1.3.0",
   "description": "Shared local workspace memory for GitHub Copilot CLI and other AI coding agents.",
   "author": {
     "name": "AVIDS2",