pi-memory-evolution 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,246 @@
+# Changelog
+
+All notable changes to pi-memory-evolution are documented here.
+
+## [0.2.0] - 2026-09-08
+
+### Changed
+
+- Rewrite the README as a concise Chinese project introduction and installation guide; move detailed operation/migration behavior to `docs/usage.md`
+- Declare public npm distribution alongside native Pi Git/local installation
+- Replace print-only package inspection with runtime-source, peer-dependency and documentation-link assertions
+- Separate operation/project-based progress nomination from answer retrieval; pending states naming a bare repository remain eligible without per-path top-2 or answer deduplication
+- Preserve important commit/push/test observations ahead of late inspection; retain completed operations before error/aborted responses without claiming whole-task completion
+- Expand bounded active-user context scanning to 4096 entries/messages and collapse repeated topic-less continuations while preserving reset/unknown-topic barriers
+- Capture natural requirement/preference/priority declarations without requiring a remember keyword; mixed statement/work sources are serialized separately instead of discarding progress
+- Exclude internal memory lookups/owned-state observations from progress evidence; include operation-resource hints and explicit observation omissions
+- Evidence-aware self-ranking after lexical gates, with separate host-assigned source weights, type-specific gradual freshness decay and non-cumulative explicit feedback
+- Schema 2/3/4 → 5 transactionally adds feedback receipts without rewriting old memories/history or inventing evidence
+- Withhold weaker proposed replacements and quarantine new conflicting variants instead of overwriting stronger user/tool evidence; fresh tool progress can still supersede prior manually corrected states
+- Short named-attribute queries cannot substitute another subject/attribute after the right answer is suppressed; query-only Chinese `多少` cleanup and numeric-value handling
+- General conversational query planning: separate asking/remembering phrases from the subject, retain current focus across multi-hop user follow-ups, and stop inheritance on explicit/unknown/reset topics
+- Evidence-based IDF for unseen terms, mandatory literal resource constraints, focused-context gates, bounded length normalization, and reduced weight for quoted questions rather than their answers
+- Track redundant facets per origin and evidence kind so a project-state replay note cannot hide a preference/fact answering the same question
+- Increase model deadline from 30 to 120 seconds and output cap from 2048 to 8192 tokens (bounded by model capability); allow up to 64 KB of validated result JSON without relaxing claim limits
+- Replaced signal/maturity/speak/proposal/approval/plan machinery with direct automatic memory evolution
+- Reuse Pi 0.85's active model and public `modelRegistry.complete`, including provider authentication
+- Store claims, sources, jobs and actual before/after history in transactional SQLite (built-in Bun/Node APIs)
+- One-time, read-only JSONL migration; unknown origins retain a visible `legacy` label, originals preserved
+- Topic-based recall across sessions and directories, including existing legacy claims without adoption
+- Capture origin is provenance and a conservative write safeguard, no longer a recall eligibility filter
+- Raw summaries never provide a lifecycle-bypassing fallback
+- Require Node 22.19+ for Node development/runtime, matching Pi 0.85's engine requirement; support the standalone Pi Bun binary
+
+### Added
+
+- Isolated real-Pi installation smoke tests for packed artifacts, Git install/update/old-pin transitions, and native npm install through a loopback registry; verify idempotent registration and memory/history preservation on removal
+- `docs/testing.md` describing installation, fake-model integration and live-provider validation boundaries
+- `/memory learning` capture/nomination diagnostics and persistent changed-record outcomes in status, distinguishing processed jobs from actual learning
+- Long-task, interruption/cancel-recovery, operation-resource, natural-intent and mixed-authority regressions; real-Pi commit/failed-push followed by 12 diagnostics, plus read-only historical replay
+- Host-assigned evidence basis/method/source/date, bounded evidence and aging labels in injection, separate quality factors in show/explain, lifecycle exclusion diagnostics
+- `/memory feedback <id> useful|unhelpful|accurate|incorrect` and narrow exact-ID user feedback statements, without paid learning calls; replay/late-event protection, quarantine/undo, unchanged evidence clock
+- Read-only `memory_recall` tool for a second explicit-topic lookup during a task, bounded to 3 claims / 2048 bytes with no query persistence in the memory database
+- Core-quality regressions and real Pi tool/feedback/provider-payload round trips with a loopback fake model
+- `/memory explain [query]`: bounded transient recall diagnostics, normalized focus/context, candidate rejection reasons and last automatic injection counts; no query/body history persisted
+- Multi-domain Chinese/English natural-question regressions, learned-alias paraphrases, multi-hop attribute refinement, unknown-topic barriers, quoted-question distractors and real-Pi provider-payload validation
+- Automatic startup and 15-second timer recovery across origins, with persisted 1m/5m/15m/1h backoff and a five-failure per-source cap plus pause warning
+- Safe fixed-code failure diagnostics, attempt/failure counts, last failure and next retry times in `/memory status`; manual evolve remains an optional one-off override
+- Transactional schema 2/3 → 4 migration preserving memory/history, automatically discovering old failures without inventing missing diagnostics
+- Recovery regressions for durable scheduling, cancellations, concurrent leases, backlog draining, migration and real-Pi timer-driven retries with a loopback fake model
+- Background consolidation after compaction or explicit user corrections, with bounded output/deadline and shutdown cancellation
+- Source idempotency, job leases, stale-result guards, exact-content suppression, and indexed/cached reads
+- Direct history/undo/search/status/evolve/adopt commands; no owner approval required
+- Strict typechecking, reproducible development dependencies, real multi-process tests and an optional real-Pi loopback-model test (local commands, not an installed CI workflow)
+- Current-branch installation/update, source deduplication, bounded retry behavior, command limits and storage recovery documentation
+- Paginated current/all/legacy memory browsing and provenance in `/memory show`
+- Follow-up regression cases and mixed lifecycle sequence testing
+- Bounded active-user context for vague follow-ups, without assistant/tool/digest feedback
+- Origin/source labels in injected claims; global list/search/history/retry and an optional `list here` view
+- Real-Pi tests that restart in another directory to verify cross-session recall, topic changes and forget
+- Word/concept retrieval with query coverage, document-frequency weighting, weak-result cutoffs and literal path handling
+- Bounded bilingual `searchTerms`, validated/persisted/undoable without refreshing evidence dates
+- Tool-backed completed-work observations that may only replace host-nominated existing project states
+- Schema 2 → 3 marker upgrade preserving existing records/history; older builds require a matching backup for rollback
+- Real-Pi bilingual/alias and temporary Git commit + failed-push tests, with no live model charges
+
+### Fixed
+
+- Natural recall questions failing or selecting the memory implementation because generic asking words diluted the actual topic
+- Recall questions containing `remember` accidentally triggering a paid learning call; explicit learning instructions remain supported
+- Unknown single-character subjects and Chinese question-particle cleanup accidentally becoming topic-less continuations or spurious query fragments
+- Failed jobs remaining stuck until manual retry, and missing durable failure reasons/times
+- Synchronize leases with longer deadlines (150 seconds by default); recover expired jobs with bounded backoff and release shutdown-cancelled work without consuming failure budgets
+- False approval/verification, ineffective thresholds and dropped deferred proposals: obsolete workflow removed
+- Cross-process lost updates and partial JSONL writes: transactional database replaces multi-file mutation
+- Parent-summary recall bypass, correction/backfill invalidation and repeated startup scans
+- CJK byte-budget overflow, truncated trust guidance, literal identifier corruption and timestamp string ordering
+- Common credential leaks, pending-source replay after suppression, async error handling and provider timeout handling
+- Control-character normalization and multiline quoted/YAML credential redaction
+- Nested/mixed Markdown fences, recursive glob preservation and sibling progress headings
+- Colon-ambiguous scoped IDs, implicit wildcard recall and same-batch cross-kind duplicates
+- Pending repeats surviving forget, unchanged legacy children lost on correction, and suppression history lost on adoption
+- Invalid before/after undo pairings, indexed identity/hash mismatches, malformed source jobs and DDL on unsupported schemas
+- Model-switch provenance, poisoned background queues, UI errors misreporting committed changes and post-shutdown reopening
+- English and long-sentence matching excerpts, unreachable legacy pages and smoke-test startup/cleanup failures
+- Pin/unpin, adoption and undo making old project-state evidence appear fresh
+- Cwd-restricted recall that contradicted the intended cross-session memory behavior
+- Weak matches such as `有没有问题` selecting `没有 CI`, and context-free continuation pulling arbitrary recent claims
+- Recall deduplication hiding distinct same-text facts from different origins
+- Weak secondary results promoted by CJK fragments, path-component words and insufficient relevance coverage
+- Current-cwd tie preference; source labels are not authority or verification weights
+- Common Chinese/English memory-boundary questions missing the actual user preference
+- Ordinary completed work not reaching evolution, leaving tracked project progress stale until compaction
+- Corrections retaining search aliases from old content, and forgetting a target leaving queued progress observers eligible
+
+## Legacy 0.1 history
+
+The phase entries below are historical implementation notes, **not current behavior or
+current safety guarantees**. Approval, shadow mode, thresholds, raw-summary recall and
+execution plans described here were removed in 0.2. Legacy document paths refer to the
+files as they existed then; see Git history or the `v0.1.0` tag for those versions.
+
+## [P11] - 2026-09-03
+
+### Added
+
+- Bounded structural extraction from labeled compaction-summary sections
+- Provisional `fact`, `preference`, `decision` and `project_state` records
+- Idempotent startup hydration for summaries created before the extractor
+- Regression coverage for section boundaries, deduplication, limits and sensitive bullets
+
+### Safety
+
+- Extraction is deterministic and offline; it never infers facts from unlabeled prose
+- Extracted records remain provisional until explicitly confirmed by the owner
+
+## [P10] - 2026-09-03
+
+### Added
+
+- Local `recent` / `durable` / `pinned` memory layers
+- Deterministic lexical + layer-authority retrieval fused with Reciprocal Rank Fusion
+- Append-only `memory-actions.jsonl` lifecycle projection
+- Explicit `/memory` commands for list, confirm, correct, forget, pin, conflict and resolve
+- Fail-closed exclusion of forgotten, conflicted and expired memories
+
+### Changed
+
+- Compaction summaries enter the recent/provisional layer by default
+
+## [P9] - 2026-09-03
+
+### Added
+
+- Durable `memories.jsonl` storage for successful Pi compaction summaries
+- Prompt-relevant cross-session retrieval using Latin-word and CJK-bigram matching
+- Continuation-prompt fallback to the most recent durable context
+- Runtime digest injection of selected durable memories
+- Basic redaction of common API keys, tokens, passwords and secrets before persistence
+- Deduplication by source compaction entry id and malformed-record tolerance
+
+### Changed
+
+- `session_compact` now persists the actual `compactionEntry.summary` while continuing to enable signal collection
+- `before_agent_start` now uses the raw user prompt to select relevant durable memories
+The format is based on [Keep a Changelog](https://keepachangelog.com/), grouped by phase.
+
+## [P8] - 2026-08-13
+
+### Added
+
+- Evidence contribution derived as `weight × relevance` (replaces hardcoded 0) and read into maturity scoring
+- Configurable speak-gate thresholds (`thresholds.json`): speakThreshold / priorityQueueThreshold / dailyDigestThreshold / suggestionLimit / strategicLimit, defaulting to Hermes values
+- Real-environment drill evidence: current pi session verified to emit agent_end signals and maturation runs in real time
+- Real pi compact fix: rpc sessions now compact successfully via multi-message accumulation (10+ alternating turns), firing a real session_compact event
+- Compact-drill configuration reverted: the temporary `compaction.keepRecentTokens=2000` setting (drill aid) was removed — multi-message accumulation is the actual fix (25K-token sessions compact under the default 20000 budget)
+
+### Changed
+
+- `evaluateCandidate` accepts optional thresholds (defaults unchanged)
+- Evidence strength now sums the contribution field
+
+### Fixed
+
+- Contribution field was a hardcoded 0 in evidence records (P2 gap)
+- Feedback collection (P1 gap): real pi `turn_end.message` carries the assistant reply, not the user input, so correction keywords were never extracted in production; feedback is now collected from user-role messages in the `agent_end` batch (verified in a real rpc session)
+
+## [P7] - 2026-08-13
+
+### Added
+
+- Approval identity recording: `approvedBy`/`approvedAt` now carry the deciding role (`assistant`/`user`) or `expiry` for auto-rejected proposals
+- Verified signal word-boundary matching: `unverified`/`未验证通过`/`not verified` no longer trigger a verified transition
+- Negated verification guard (`未验证通过`/`未验证完成`/`未通过验证`/`not verified`/`not verification passed`/`never verified`)
+- Shadow calibration observation guide in `docs/design.md`
+
+### Changed
+
+- `transitionProposal` accepts an optional approval identity payload (approved/rejected only)
+- Auto-approval journal lines now include the deciding role
+
+### Fixed
+
+- `unverified P-xxx` previously advanced implemented proposals to verified (substring match on `verified`); now stays implemented
+
+## [P6] - 2026-08-13
+
+### Added
+
+- Word-boundary approval matching: `approved`/`token`/`okay` no longer trigger approval decisions
+- Negated approval guard (`不执行`/`不批准`/`不同意`/`不可以` now reject instead of approve)
+- Evidence carry: matured candidates and execution plans now include real collected evidence records
+- Execution plan archive: terminal proposals move plans to `executions/archive/`, purged after 90 days
+- Verified signal trigger: implemented proposals advance to verified via agent message with a verification keyword
+
+### Fixed
+
+- Residual false-approval vector: tool results can no longer trigger approval decisions (role whitelist)
+
+## [P5] - 2026-08-13
+
+### Added
+
+- Proposal lifecycle state machine (pending_user_approval → approved/rejected → implemented → verified, with failed/rollback_required paths)
+- Auto-approval channel: proposals surface in the runtime digest; the agent approves/rejects by referencing the proposal id; 24h expiry auto-rejects
+- Record-first evolution executor: approved proposals produce markdown execution plans in `executions/`
+
+### Changed
+
+- Proposal approval moved from `ui.confirm()` to the auto-approval channel
+
+## [P4] - 2026-08-13
+
+### Added
+
+- Speak gate consuming matured candidates: priority/speak scoring, risk dampeners, daily quotas, traceable decisions
+- Proposal queue: approved candidates written as proposals
+
+## [P3] - 2026-08-13
+
+### Added
+
+- Runtime digest injection into every session (`before_agent_start`), <2KB, expiry-stamped, advisory-only
+
+## [P2] - 2026-08-07
+
+### Added
+
+- Memory evaluation using the Hermes maturation formula (evidence-driven, "time is not evidence")
+- Agenda engine: state machine, unmatched-signal clustering, maturation pipeline
+- Shadow mode: evaluation writes candidates and journal only, never triggers user-visible actions
+
+## [P1] - 2026-08-05
+
+### Added
+
+- Signal collection: session stats, projection notices, user feedback → `signals.jsonl`
+- Evolution journal (`evolution_journal.md`)
+- Compaction-gated collection trigger and subagent-process skip
+
+## [P0] - 2026-08-04
+
+### Added
+
+- Extension skeleton with capability probing and version-decoupling adapter layer
+- `before_agent_start` lifecycle hook placeholder
+- node:test suites

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 btnalit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# pi-memory-evolution
+
+为 [Pi](https://pi.dev) 提供持久记忆，让项目背景、个人偏好和工作进展能够跨会话延续。
+
+扩展自动学习值得保留的信息，在后续对话中按主题注入相关内容，也支持跨目录召回。不需要反复说“记住”，不需要维护审批队列。
+
+## 功能
+
+- **自动学习与更新**：从对话摘要、需求和纠正中提取记忆，根据实际工具结果更新已有项目状态；保留来源和变更历史，支持衰退、排序与撤销。
+- **相关内容注入**：结合当前问题和近期用户上下文选择记忆，过滤弱匹配和失效状态；没有匹配就不填充无关内容。
+- **跨会话召回**：在共享记忆库的不同会话、目录中查找背景；提供只读 `memory_recall` 工具，供助手在任务中途补查。
+
+学习使用 Pi 当前模型和已有认证，无需另配 API Key、向量数据库或嵌入服务。
+
+## 安装
+
+需要 **Pi 0.85+**，并已配置可用模型。使用 npm 版 Pi 时需要 **Node.js 22.19+**。
+
+### npm
+
+```bash
+pi install npm:pi-memory-evolution
+```
+
+### Git
+
+也可以直接安装 Git 默认分支，需要本机有 Git 和 npm：
+
+```bash
+pi install https://github.com/btnalit/pi-memory-evolution
+```
+
+**两种方式选一种**，不要重复安装。然后在 Pi 中执行：
+
+```text
+/reload
+/memory status
+```
+
+出现 `SQLite ok (schema 5)` 表示存储初始化成功。后续正常使用 Pi 即可，学习和召回会自动运行。
+
+## 使用
+
+在对话中说明需求，例如：
+
+```text
+atlas-service 的核心需求是自动备份和故障恢复。
+```
+
+之后可以在新会话中继续询问：
+
+```text
+你还记得 atlas-service 的核心需求吗？
+```
+
+学习在后台完成，并非每句话都会保存。可用以下命令查看和维护记忆：
+
+| 命令 | 用途 |
+| --- | --- |
+| `/memory list` | 浏览记忆 |
+| `/memory search <主题>` | 搜索相关内容 |
+| `/memory show <id>` | 查看内容和来源 |
+| `/memory learning` | 查看采集、更新及实际变更结果 |
+| `/memory explain` | 查看上一次自动注入的选择原因 |
+| `/memory correct <id> <内容>` | 纠正记忆 |
+| `/memory forget <id>` | 停止召回该记忆 |
+
+完整命令、安装迁移和排错方法见[使用指南](docs/usage.md)。
+
+## 更新与卸载
+
+npm 安装：
+
+```bash
+pi update npm:pi-memory-evolution
+pi remove npm:pi-memory-evolution
+```
+
+Git 安装请把上面的包来源替换为安装时使用的仓库 URL。操作后执行 `/reload` 或重启 Pi。卸载扩展不会删除记忆库；升级数据库结构前请先退出共用该库的 Pi 进程并备份。
+
+## 数据与边界
+
+数据默认保存在 `~/.pi/agent/agent-suite/memory-evolution/`，使用本地 SQLite。`PI_CODING_AGENT_DIR` 可改变存储前缀；不同工作目录默认共享记忆库。
+
+学习会将经过过滤的来源内容发送给当前模型，并消耗相应额度。记忆不是经过独立验证的事实，匹配和敏感信息过滤也并非万无一失；重要内容仍需核实。详见[存储与隐私](docs/usage.md#local-storage-and-provenance)。
+
+## 开发
+
+在源码仓库中运行：
+
+```bash
+npm ci --ignore-scripts
+npm run check
+npm run test:install
+npm run test:pi
+```
+
+安装测试使用隔离环境，集成测试使用真实 Pi 和模拟模型，不产生付费模型调用。环境要求和测试范围见[测试说明](docs/testing.md)。
+
+## 文档
+
+[使用指南](docs/usage.md) · [架构设计](docs/design.md) · [记忆质量](docs/core-quality.md) · [更新记录](CHANGELOG.md)
+
+## 许可证
+
+[MIT](LICENSE)

package/docs/conversation-recall.md

@@ -0,0 +1,94 @@
+# Conversational recall follow-up
+
+Version 0.2.0 remains unreleased. This change improves automatic **per-user-turn**
+recall, not only startup recall, and does not add a special case for a device/topic.
+No schema change, production-memory rewrite or additional recall-time model call.
+
+## Reproduced failures
+
+The initial 13 regression groups had **9 failures** on the preceding implementation.
+Six groups each exercise Chinese/English questions about a different domain: device,
+database, backup, font, coffee and travel. Recall framing could either dilute the actual
+subject or retrieve an unrelated memory about the memory system itself. Other failures
+covered exact-resource precision, corpus-size sensitivity and learned-alias paraphrases.
+
+A read-only production-database replay separately reproduced the original issue:
+a one-word topic found records, while the natural question yielded none. This was not
+a missing record, a cwd restriction, an expired job or a need for another model API key.
+
+## Implementation
+
+- **Query planning:** query-only cleanup removes conversational framing while preserving
+  actual technical memory questions and exact paths. Stored text is unchanged.
+- **Multi-hop context:** a structured plan separates current focus from its supporting
+  subject. `SQLite 数据库 → 端口呢？ → 认证呢？ → 继续` retains SQLite and answers the
+  authentication question, not the earlier port question. Only bounded active-branch
+  user texts/retained user tails supply context; never assistant/tool/injected text.
+- **Topic barriers:** new subjects, including unknown subjects, do not inherit the last
+  successful database match. Reset phrases break the chain. Context-free continuation
+  stays empty. Unindexed single-character subjects are not treated as empty chit-chat.
+- **Multi-signal ranking:** words, exact identifiers, bilingual concepts and validated
+  learned aliases contribute field-weighted evidence. Unseen terms get base weight,
+  not maximum IDF. Coverage, current-focus and supporting-subject gates, mandatory
+  literal constraints, mild length normalization and relative relevance filtering
+  protect precision rather than indiscriminately lowering thresholds.
+- **Question vs answer:** quoted questions in replay/incident notes have reduced weight
+  and cannot qualify by themselves. Facet deduplication is separated by evidence kind,
+  preventing a project-state mention from hiding a preference that answers the question.
+- **No accidental learning:** asking `What do you remember about X?` does not turn the
+  question into a learning source simply because it contains `remember`. Explicit
+  `Please remember that ...` instructions still work.
+- **Inspection:** `/memory explain` shows the last automatic snapshot, including actual
+  injection count/bytes. `/memory explain <query>` previews an explicit query without
+  conversation inheritance or replacing that snapshot. Diagnostics contain bounded,
+  sanitized features/IDs/counts/reasons, not memory bodies, and are not persisted.
+  They show selection/injection decisions, not whether the model understood them.
+
+The exact scoring rules, lifecycle exclusions and limits are in [design.md](design.md).
+The digest still contains at most three claims / 2,048 UTF-8 bytes, with reserved trust
+and provenance guidance and an explicit warning that this is not the full inventory.
+
+## Validation
+
+- **164 tests passed**, including existing transactional/lifecycle/privacy tests and new
+  conversational regressions. Strict TypeScript checking and package dry-run inspection
+  are included in `npm run check`.
+- Six domains × six natural-question forms, positive learned-alias paraphrases and
+  unsupported-paraphrase negatives. These are deterministic fixtures, not a universal
+  natural-language benchmark or an independent semantic-accuracy evaluation.
+- Multi-hop current-focus tests distinguish SQLite authentication from PostgreSQL
+  authentication and from SQLite's old port answer. Unknown facets do not fall back to
+  old answers; new subjects and resets do not resurrect older matched topics.
+- Real installed Pi 0.85/Bun with a **loopback fake model** verifies actual outgoing
+  provider digests, fresh cross-directory sessions, Chinese/English question framing,
+  multi-hop refinements, unknown-topic barriers, diagnostics, forget and no accidental
+  learning calls. Existing model/auth, actual temporary Git work, failed-push and timer
+  recovery checks remain included. No live paid provider was used for these tests.
+- A separate **read-only SQLite connection** evaluated 14 distinct query/context cases
+  against a snapshot of **154 real records** (17 executions including repeats). The
+  original natural questions now retrieve the stored topic. Both language variants of
+  the project-boundary question rank the actual preference first, not a replay note
+  quoting the question or a weak storage-directory fact. Unknown/reset/context-free
+  cases remain empty. Model/auth questions retrieve corresponding implementation facts.
+  The connection reported `total_changes() = 0`. Sample timing was 0–56 ms per evaluation
+  (empty queries at 0 ms); this is one local sample, not a performance guarantee.
+
+The live Pi process may independently learn from later completed turns; these counts
+refer to the diagnostic snapshot, not a promise that the running database stays frozen.
+
+## Limits and activation
+
+This is **local concept/alias-assisted retrieval**, not an embedding service or a general
+LLM semantic reasoner. Learned aliases extend vocabulary without translating at recall
+time; absent aliases, unsupported paraphrases can still be missed. Conservative subject
+and literal gates can miss useful ambiguous references. Negation, complex comparisons
+and arbitrary coreference are not fully understood. The system deliberately prefers no
+injection over filling a quota with unrelated memories.
+
+Selection is not truth verification. Historical states may be stale even inside their
+seven-day window, and inferred claims/aliases remain provisional. Existing facts are
+not marked complete or rewritten merely because the algorithm changed.
+
+The local Pi installation references the checkout directly. Run **`/reload`** (or restart)
+to activate the updated extension in an existing session. This change does not migrate
+or reset the database. It neither commits nor publishes the repository automatically.