AutoGineer
Generated banner for mempal
Generated logo for mempal

mempal

Memory framework

First committed by ZhangHanDong

Published in ZhangHanDong/mempal. Publisher page

284 GitHub stars

What it is

AI Agent Memory
— the description by ZhangHanDong

AutoGineer overview, from the brain’s own files

Mempal is a project memory system designed for coding agents, implemented as a single binary. It enables agents to store, search, and retrieve decision context across sessions. The system utilizes a hybrid search approach combining BM25 keyword matching and vector semantic search, alongside a knowledge graph for tracking entity relationships. It includes a self-describing protocol that allows agents to understand how to interact with the memory system without manual system prompt configuration. Mempal supports cross-project tunnels, multilingual embedding, and collaborative agent workflows through inbox-based handoffs.

How it works

Memory model: Hybrid

AutoGineer overview, from the brain’s own files

Mempal stores data in a SQLite database located at ~/.mempal/palace.db. It ingests project information by chunking and embedding content, which is then searchable via CLI or MCP tools. The system uses a memory protocol to guide agent behavior, such as verifying facts before ingestion and citing sources. It supports collaborative agent interactions by allowing agents to push messages to a per-project inbox, which are then processed via hooks during user prompt submission. The knowledge graph tracks triples with temporal validity, and the system provides tools for fact-checking and context assembly.

Folders
FolderRoleFiles
.claudeagent-config2
.githubagent-config3
docsdocs129
hookshooks2
srcsource-code30
teststests31
benchmarksfolder1
booksfolder41
cratesfolder71
specsfolder131

The agent writes

Requirements

Runtimes: Rust

Databases: SQLite

Works with: Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Kiro, OpenCode, Amp, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. This brain runs code automatically: 2 hooks (claude-code). Review .claude/settings.json before opening the folder in Claude Code. No step below turns a hook on for you.

    • .claude/settings.json: if echo "$TOOL_INPUT" | grep -q 'git commit'; then echo 'MEMPAL REMINDER: You just committed code. Call mempal_ingest to save the decision context (what was built, why, what was considered). Rule 4: SAVE AFTER DECISIONS.'; fi
    • .claude/settings.json: bash .claude/hooks/user-prompt-submit.sh
  2. Not scanned by AutoGineerThe author’s MCP configuration (.mcp.json) also starts it in a way AutoGineer does not offer. Read that file: AutoGineer did not scan that path; what it runs is listed under “This brain runs”. https://github.com/ZhangHanDong/mempal/blob/9ed705d78321daf5878e9579777b1a471e97c6f1/.mcp.json
  3. Not scanned by AutoGineerThe author’s README also describes installing it with cargo. Read its install section: AutoGineer did not scan that path. https://github.com/ZhangHanDong/mempal/blob/9ed705d78321daf5878e9579777b1a471e97c6f1/README.md#quick-start

  4. First committed by ZhangHanDong. Published in ZhangHanDong/mempal. Licence: MIT License.

Usage

AutoGineer overview, from the brain’s own files

  • Initialize project memory for a directory
  • Ingest project files into a specific wing
  • Perform hybrid search for past decisions
  • Fact-check assertions against the knowledge graph
  • Collaborate between agents using inbox pushes
  • Manage knowledge lifecycle and anchor publication
“mempal search "auth decision clerk"”
Returns past decisions related to authentication and Clerk, including source citations.
“mempal fact-check path/to/file”
Identifies potential contradictions like similar name conflicts or stale facts against the knowledge graph.

Documentation by ZhangHanDong

mempal

Image: Crates.io Image: Downloads Image: docs.rs Image: CI Image: Release Image: License: MIT

Project memory for coding agents. Single binary, cargo install mempal, find past decisions with citations in seconds.

Latest release: v0.9.1 (2026-08-19).

What It Does

Agent writes code → commits → mempal saves the decision context
Next session (any agent) → mempal search → finds the decision with source citation

  • Hybrid search: BM25 keyword matching + vector semantic search, merged via Reciprocal Rank Fusion

  • Knowledge graph: subject-predicate-object triples with temporal validity (valid_from/valid_to)

  • Cross-project tunnels: automatic discovery when the same room appears in multiple wings

  • Self-describing protocol: MEMORY_PROTOCOL embedded in MCP ServerInfo teaches any agent how to use mempal — no system prompt configuration required

  • Multilingual: model2vec-rs (BGE-M3 distilled) as default embedder, zero native dependencies

  • Single file: everything lives in ~/.mempal/palace.db (SQLite + sqlite-vec)

Quick Start

cargo install mempal --version 0.9.1 --locked

mempal init ~/code/myapp
mempal ingest ~/code/myapp --wing myapp
mempal search "auth decision clerk"
mempal wake-up

With REST support:

cargo install mempal --version 0.9.1 --locked --features rest

From a source checkout:

cargo install --path . --locked

Configuration

Config at ~/.mempal/config.toml (optional, defaults work without it):

db_path = "~/.mempal/palace.db"

[embed]
backend = "model2vec"                          # default, zero native deps
# model = "minishlab/potion-multilingual-128M" # default multilingual model (1024d)

Other backends:

# Local ONNX (requires --features onnx)
[embed]
backend = "onnx"

# External API
[embed]
backend = "api"
api_endpoint = "http://localhost:11434/api/embeddings"
api_model = "nomic-embed-text"
dimensions = 768  # optional; defaults to 384 when omitted

Commands

CommandPurpose
mempal init <DIR> [--dry-run]Infer wing/rooms from project tree
mempal ingest <DIR> --wing <W> [--dry-run]Chunk, embed, and store
mempal search <QUERY> [--wing W] [--room R] [--json]Hybrid search (BM25 + vector + RRF)
mempal wake-up [--format aaak]Context refresh, sorted by importance
mempal compress <TEXT>AAAK format output
mempal delete <DRAWER_ID>Soft-delete a drawer
mempal purge [--before TIMESTAMP]Permanently remove soft-deleted drawers
mempal kg add <S> <P> <O>Add a knowledge graph triple
mempal kg query [--subject S] [--predicate P]Query triples
mempal kg timeline <ENTITY>Chronological view of an entity
mempal kg statsKnowledge graph statistics
mempal tunnelsCross-wing room links
mempal taxonomy list / editManage routing keywords
mempal reindexRe-embed all drawers after model change
mempal statusDB stats, schema version, scopes
mempal serve [--mcp]MCP server (+ REST with feature)
mempal cowork-install-hooks [--global-codex]Install UserPromptSubmit hooks for Claude Code (+ optional Codex merge)
mempal cowork-drain --target <claude|codex>Drain inbox messages (for hook use; exits 0 on any failure)
mempal cowork-status --cwd <PATH>Read-only view of both inboxes at <PATH>
mempal fact-check [PATH|-] [--wing W] [--room R] [--now <UNIX_SECS>]Offline contradiction check against KG triples + known entities
mempal bench longmemeval <FILE>LongMemEval retrieval benchmark
Project ignore rules

mempal init <DIR> and directory-mode mempal ingest <DIR> use the target project's ignore rules by default. They respect .gitignore, .git/info/exclude, global Git excludes, and a root-level .mempalignore. Built artifacts that should never become project memory can be listed in .mempalignore without changing the project's Git behavior.

Use --ignore-file <PATH> to add one or more extra ignore files for a run. Use --no-gitignore or --no-mempalignore to disable either default source. Explicit file ingest remains explicit: mempal ingest path/to/file --wing <W> still ingests that file even if the project ignore rules would skip it during directory traversal.

MCP Server (10 tools)

mempal serve --mcp exposes these tools via Model Context Protocol:

ToolPurpose
mempal_statusState + protocol + AAAK spec (teaches agent on first call)
mempal_searchHybrid search with tunnel hints, citations, and AAAK-derived structured signals
mempal_ingestStore memories with optional importance (0-5) and dry_run; reports lock_wait_ms when concurrent ingest was observed
mempal_deleteSoft-delete with audit trail
mempal_taxonomyList or edit routing keywords
mempal_kgKnowledge graph: add/query/invalidate/timeline/stats
mempal_tunnelsCross-wing room discovery
mempal_peek_partnerRead partner agent's live session (Claude ↔ Codex), pure read, never writes
mempal_session_peekRead an explicit Claude/Codex local session by concrete tool + cwd, including same-tool cross-project reads
mempal_cowork_pushSend a short handoff message to partner agent's inbox (at-next-submit delivery)
mempal_fact_checkOffline contradiction detection vs KG triples + known entities (similar-name, relation mismatch, stale facts)

The server embeds MEMORY_PROTOCOL (11 behavioral rules) in the MCP initialize.instructions field. Any MCP client learns the workflow automatically.

Memory Protocol

mempal teaches agents these rules through self-description:

  1. FIRST-TIME SETUP — call mempal_status to discover wings before filtering

  2. WAKE UP — different clients have different pre-load mechanisms

  3. VERIFY BEFORE ASSERTING — search before stating project facts

  4. QUERY WHEN UNCERTAIN — search on "why did we...", "last time we..." 3a. TRANSLATE TO ENGLISH — translate non-English queries before searching

  5. SAVE AFTER DECISIONS — persist rationale, not just outcomes

  6. CITE EVERYTHING — reference drawer_id and source_file 5a. KEEP A DIARY — record behavioral observations in wing="agent-diary"

  7. PARTNER AWARENESS — use mempal_peek_partner for live partner-agent session, mempal_session_peek for explicit same-tool/cross-project local sessions, and mempal search only for crystallized drawers

  8. DECISION CAPTURE — mempal_ingest is for firm decisions only; include partner input when peek informed the call

  9. COWORK PUSH — use mempal_cowork_push as the SEND primitive in the SEND/READ/PERSIST triad; at-next-submit delivery, not real-time

  10. VERIFY BEFORE INGEST — call mempal_fact_check before persisting a decision that asserts entity relationships; it catches similar-name typos, relation mismatches against the KG, and stale facts with expired valid_to

Agent Cowork (P6 peek + P8 push)

Two coding agents (Claude Code and Codex) can collaborate on the same repo through a per-project inbox + hook-driven injection channel, on top of mempal_peek_partner (read live partner session), mempal_session_peek (read an explicit local session by concrete tool + cwd), and mempal_cowork_push (send ephemeral handoff).

Install hooks once per repo (run at the repo root):

mempal cowork-install-hooks --global-codex

This writes:

  • .claude/hooks/user-prompt-submit.sh + merges a registration entry into .claude/settings.json so Claude Code fires the hook on every user prompt.

  • ~/.codex/hooks.json UserPromptSubmit entry so Codex fires the same drain on every user prompt.

The --global-codex part is optional. The re-run is idempotent and self-heals stale/wrong drain entries — re-installing after a mempal upgrade is always safe.

Delivery is at-next-UserPromptSubmit, not real-time: a push from Claude to Codex becomes visible only when the Codex user submits their next prompt, at which point the hook drains the inbox and prepends the message as additionalContext on that turn.

Check inbox state at any time without draining:

mempal cowork-status --cwd "$PWD"
Known limitations

  • Codex feature flag dependency: Codex's hooks runtime is gated behind the codex_hooks feature flag (currently "under development" in shipped codex-cli). If the flag is off, Codex silently ignores ~/.codex/hooks.json. install-hooks detects this and prints a warning with the activation command: codex features enable codex_hooks.

  • Two Claude-side artifacts: Claude Code does not auto-discover hook scripts by filename. Both .claude/hooks/user-prompt-submit.sh and the matching entry in .claude/settings.json are required. install-hooks writes both; do not remove either by hand.

  • TUI restart needed after config changes on the Codex side: Codex reads config.toml + hooks.json at process startup only. After enabling the feature flag or running install-hooks, fully quit and relaunch the Codex TUI before expecting hooks to fire.

  • MCP server re-spawn: Claude Code spawns the mempal MCP server at client startup. After upgrading the mempal binary (cargo install ...), restart Claude Code so the MCP server respawns and exposes newly added tools like mempal_cowork_push or mempal_fact_check.

  • Bidirectional scope: mempal_cowork_push currently requires an MCP client identifying itself as claude-code or codex (or their aliases). Generic MCP clients cannot push because caller identity is required to fill the from field and enforce self-push rejection. This is by design for the Claude ↔ Codex pair.

Concurrent Ingest Safety (P9-B)

Two agents writing to the same source simultaneously used to be a TOCTOU race: both would pass the dedup check, both would insert, producing duplicate drawers or mismatched vectors. Since 0.4.0, mempal_ingest and ingest_file_with_options acquire a per-source advisory lock before entering the dedup + insert critical section.

  • Lock files live at ~/.mempal/locks/<16-hex>.lock, created lazily, released on guard drop.

  • 5 s timeout, 50 ms retry + jitter; LockError::Timeout surfaces as an ingest error.

  • Every non-dry-run response carries lock_wait_ms: Option<u64> so agents can detect contention.

  • Dry-run does not acquire the lock (no writes, no race).

  • Unix only in 0.4.0. On Windows the lock path is a no-op fallback; LockFileEx support is tracked for a follow-up.

Offline Fact Checking (P9-A)

mempal_fact_check — and its CLI counterpart mempal fact-check — compare a text blob against the existing KG triples + the entity registry derived from recent drawers. It flags three issue classes, all deterministic and zero-LLM:

IssueTrigger
SimilarNameConflictText mentions a name within Levenshtein distance ≤ 2 of a known entity, and the names are not equal.
RelationContradictionText asserts a predicate (e.g. brother_of) that's in the incompatibility dictionary against an existing KG triple with the same (subject, object) endpoints.
StaleFactText asserts a triple whose KG row has valid_to < now (Unix seconds).

Extracted triples today cover three narrow patterns: "X is Y's ROLE", "X works at / for Y", and "X is [the|a|an] ROLE of Y". Unknown sentence shapes are silently ignored, so the tool errs toward under-reporting rather than false positives.

Protocol Rule 11 guides agents to run this before ingesting a decision that asserts entity relationships. See specs/p9-fact-checker.spec.md for the full contract.

Search Architecture

query → BM25 (FTS5)     → ranked by keyword match
      → Vector (sqlite-vec) → ranked by semantic similarity
      → RRF Fusion (k=60)   → merged ranking
      → Wing/Room filter     → scoped results
      → Tunnel hints         → cross-project references

Knowledge Graph

mempal kg add "Kai" "recommends" "Clerk"
mempal kg add "Clerk" "replaced" "Auth0" --source-drawer drawer_xxx
mempal kg timeline "Kai"
mempal kg stats

Triples support temporal validity — relationships can be invalidated when they expire.

Agent Diary

Cross-session behavioral learning — agents record observations, lessons, and patterns:

# Search diary entries
mempal search "lesson" --wing agent-diary
mempal search "pattern" --wing agent-diary --room claude

Diary entries use the existing mempal_ingest tool with wing="agent-diary" and room=agent-name. MEMORY_PROTOCOL Rule 5a teaches agents to write diary entries. Integrates with Claude Code's auto-dream for automatic memory consolidation.

Ingest Formats (5)

FormatAuto-detected by
Claude Code JSONLtype + message fields
ChatGPT JSONArray or mapping tree
Codex CLI JSONLsession_meta + event_msg entries
Slack DM JSONtype: "message" + user + text
Plain textFallback

AAAK Compression

Output-only format readable by any LLM without decoding:

mempal compress "Kai recommended Clerk over Auth0 based on pricing and DX"
# V1|manual|compress|1744156800|cli
# 0:KAI+CLK+AUT|kai_clerk_auth0|"Kai recommended Clerk over Auth0..."|★★★★|determ|DECISION

Chinese text uses jieba-rs POS tagging for proper word segmentation.

Architecture

CrateResponsibility
mempalInstallable CLI package, REST entrypoint, and legacy facade paths
mempal-embedPublic Embedder / EmbedderFactory traits, API embedder, model2vec and ONNX implementations
mempal-search-corePublic FTS5 query escaping and RRF rank-fusion primitives
mempal-agent-memoryPublic agent-memory domain types and anchor helpers
mempal-mcp-protocolPublic self-describing MEMORY_PROTOCOL text
mempal-store-sqlitePublic SQLite storage layer: schema, migrations, Database, FTS5, sqlite-vec, KG, tunnels, cards, adoption tables
mempal-runtimePublic runtime workflows: ingest, search orchestration, context, brief, knowledge, factcheck, projects, cowork, doctor, AAAK
mempal-mcp-serverPublic MCP server adapter and tool wiring for the runtime

Key design choices:

  • model2vec-rs default embedder — zero native deps, multilingual (BGE-M3 distilled)

  • ort (ONNX) available behind onnx feature flag for max quality

  • FTS5 for BM25 keyword search — synced via SQLite triggers

  • Soft-delete with audit trail — mempal delete + mempal purge

  • Importance ranking — drawers have 0-5 importance, wake-up sorts by importance

  • Semantic dedup — ingest warns (doesn't block) when similar content exists

  • Public workspace crates — reusable libraries are maintained in this repo and published as versioned crates while cargo install mempal remains the CLI path. P114 keeps the split coarse: storage, runtime, and MCP server are separate crates, but feature families such as knowledge, cowork, and context remain in mempal-runtime.

Development

cargo test --workspace
cargo test --workspace --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo fmt --all --check

After changing the embedding model or dimensions, re-embed existing drawers:

mempal reindex

Docs

Book: MemPalace — Reforging Memory in Rust

mempal 的设计分析和完整技术叙事，收录在《MemPalace: AI 记忆的第一性原理》Part 10（第 26-30 章）：

章节内容
第 26 章为什么用 Rust 重铸 — 触发点、重写判断、语言选择
第 27 章保留了什么、改变了什么 — 5 维度对比 + 架构图
第 28 章自描述协议 — MEMORY_PROTOCOL、7 条规则、agent 生命周期
第 29 章多 Agent 协作 — Claude↔Codex 接力、反模式发现、agent 日记
第 30 章诚实的差距 — benchmark 数据、6 个 gap

CLAUDE.md

mempal

Rust 实现的 coding agent 项目记忆工具。单二进制，cargo install mempal，10 秒内带出处找回历史决策。

Skills

必须使用项目内的 Rust 技能：skills/rust-skills/SKILL.md

编写、审查、调试、重构 Rust 代码时，遵循该 skill 的四步工作流（理解 → 服从 → 释放 → 约束）和概念锚点框架。

参考实现

mempal 借鉴 MemPalace 的设计理念（verbatim 存储、Wing/Room 结构、AAAK 压缩），用 Rust 从零实现并修复其缺陷。以下两个本地项目是关键参考：

  • MemPalace 源码：/Users/zhangalex/Work/Projects/AI/mempalace — Python 原版实现，查看 mempalace/ 目录下的 searcher.py、palace_graph.py、dialect.py、knowledge_graph.py 等模块了解原始设计

  • MemPalace 书稿：/Users/zhangalex/Work/Projects/AI/mempalace-book — 基于源码的设计分析书，book/src/ 下 30 章（含 Part 10 mempal Rust 重铸）+ 4 个附录

实现时遇到设计疑问，优先查阅书稿中的分析（特别是附录 C 的 AAAK 评估和附录 A/B 的 E2E Trace），而非直接复制 Python 代码。

设计文档

docs/specs/2026-04-08-mempal-design.md — 完整架构设计，所有实现必须以此为准。

Spec 体系

项目使用 agent-spec 管理任务合约。所有实现必须对照 spec 验收。

硬规则：

  • 每一个 numbered P 都必须留下 specs/pNN-*.spec.md。

  • 每一个 numbered P 都必须留下匹配的 docs/plans/*pNN*.md。

  • 该规则同样适用于文档-only、audit-only、policy-only 和代码实现类 P。

  • future spec-less P 不能算完成；missing spec 必须先补齐再实现或合并。

  • 完成后必须同步更新 AGENTS.md / CLAUDE.md 的 spec 与 plan inventory。

项目级 Spec

  • specs/project.spec.md — 项目约束（edition、依赖、编码规范、架构不变量）

已完成的 Spec（P0-P28）
Spec状态范围
specs/p0-core-scaffold.spec.md完成workspace 骨架 + SQLite schema
specs/p0-embed-trait.spec.md完成Embedder trait（model2vec 默认 + ort 可选）
specs/p0-ingest.spec.md完成导入管道（格式检测/归一化/分块/存储）
specs/p0-search-cli.spec.md完成搜索引擎 + CLI
specs/p1-routing-citation.spec.md完成查询路由 + 引用组装
specs/p2-mcp.spec.md完成MCP 服务器（7 工具）
specs/p3-aaak.spec.md完成AAAK 编解码（BNF + 往返验证）
specs/p4-rest-api.spec.md完成REST API（feature-gated）
specs/p5-wake-up-importance.spec.md完成L1 重要性排序 wake-up（schema v4）
specs/p5-kg-timeline-stats.spec.md完成KG timeline + stats actions
specs/p5-semantic-dedup.spec.md完成语义去重检测（ingest warning）
specs/p5-agent-diary.spec.md完成Agent 日记 convention（协议层）
specs/p5-format-support.spec.md完成Slack DM + Codex CLI 格式支持
specs/p6-cowork-peek-and-decide.spec.md完成Claude↔Codex 协作：live session peek（mempal_peek_partner）+ Rule 8/9
specs/p7-search-structured-signals.spec.md完成mempal_search 响应每条结果附带 5 个 AAAK-derived 结构化字段（entities / topics / flags / emotions / importance_stars），content 保持 raw
specs/p8-cowork-inbox-push.spec.md完成双向 cowork push — mempal_cowork_push MCP 工具 + cowork-drain / cowork-status / cowork-install-hooks CLI + 对称 UserPromptSubmit hook 注入（at-next-submit 交付）
specs/p9-fact-checker.spec.md完成离线事实核查 — mempal_fact_check MCP 工具 + fact-check CLI，基于 KG triples + 已知 entity 检测 SimilarNameConflict / RelationContradiction / StaleFact（协议 Rule 11）
specs/p9-ingest-lock.spec.md完成Per-source flock 锁 — 消除 Claude↔Codex 并发 ingest 同一 source 的 TOCTOU race；IngestStats / IngestResponse.lock_wait_ms 提供并发等待可观测性
specs/p10-explicit-tunnels.spec.md完成schema v6 + mempal_tunnels 扩 add/list/delete/follow 显式跨 wing 链接
specs/p10-normalize-version.spec.md完成schema v7 normalize_version 列 + reindex --stale 机制
specs/p11-transcript-noise-strip.spec.md完成Claude/Codex transcript noise strip + CURRENT_NORMALIZE_VERSION=2
specs/p11-chunk-neighbors.spec.md完成mempal_search / CLI search 可选返回命中 chunk 前后邻居
specs/p11-diary-daily-rollup.spec.md完成agent-diary 天粒度 upsert drawer，防 chatty agent 爆炸
specs/p12-mind-model-bootstrap.spec.md完成Stage-1 mind-model bootstrap：typed drawers + dao/shu/qi 最小治理字段 + global/repo/worktree anchor metadata
specs/p13-wake-up-statement.spec.md完成wake-up 最小闭环：knowledge drawer 优先按 statement 唤醒，evidence 继续按 content 唤醒
specs/p13-ingest-identity.spec.md完成typed/bootstrap ingest drawer_id identity parity：MCP / REST / 文件入口统一使用 bootstrap identity components
specs/p14-context-assembler.spec.md完成mind-model runtime assembler：mempal context 按 dao_tian -> dao_ren -> shu -> qi -> evidence 和 worktree -> repo -> global 组装 context pack
specs/p15-mcp-context.spec.md完成mempal_context MCP 工具：向 agent runtime 暴露 P14 mind-model context pack
specs/p16-context-skill-guidance.spec.md完成context-guided skill selection protocol：mempal_context 辅助 workflow/skill/tool 选择，但 trigger_hints 只做 bias、不自动执行
specs/p17-knowledge-lifecycle.spec.md完成bootstrap knowledge lifecycle CLI：mempal knowledge promote/demote 受约束更新 knowledge drawer status 与 refs，并写 audit
specs/p18-knowledge-distill.spec.md完成bootstrap knowledge distill CLI：mempal knowledge distill 从 evidence refs 创建 candidate knowledge drawer
specs/p19-lifecycle-ref-validation.spec.md完成lifecycle evidence ref hardening：promote/demote refs 必须是存在的 evidence drawers
specs/p20-promotion-gate-policy.spec.md完成read-only promotion gate policy：mempal knowledge gate 评估 knowledge drawer 是否满足最小提升门槛
specs/p21-mcp-knowledge-gate.spec.md完成mempal_knowledge_gate MCP 工具：向 agent runtime 暴露 P20 read-only promotion gate
specs/p22-mcp-knowledge-distill.spec.md完成mempal_knowledge_distill MCP 工具：从 evidence refs 创建 candidate knowledge drawer
specs/p23-mcp-knowledge-lifecycle.spec.md完成mempal_knowledge_promote / mempal_knowledge_demote MCP 工具：gate-enforced promotion + evidence-backed demotion
specs/p24-anchor-publication.spec.md完成mempal knowledge publish-anchor CLI：显式 outward anchor publication（worktree -> repo -> global）
specs/p25-mcp-anchor-publication.spec.md完成mempal_knowledge_publish_anchor MCP 工具：显式 outward anchor publication
specs/p26-dao-tian-runtime-budget.spec.md完成mempal context / mempal_context 默认最多注入 1 条 dao_tian，支持显式禁用或提高预算
specs/p27-knowledge-policy-surface.spec.md完成mempal knowledge policy / mempal_knowledge_policy：只读 Stage-1 promotion policy 阈值表
specs/p28-field-taxonomy-surface.spec.md完成mempal field-taxonomy / mempal_field_taxonomy：只读 Stage-1 field taxonomy guidance
specs/p29-wake-up-context-boundary.spec.md完成固化 wake-up 与 mind-model context 边界：wake-up 保持 L0/L1 refresh，typed dao/shu/qi 组装只属于 mempal context / mempal_context
specs/p30-knowledge-card-storage-boundary.spec.md完成固化 Phase-2 knowledge card 存储边界：未来 knowledge_cards 使用同一个 SQLite palace.db 的独立表，不拆外部 persistence layer
specs/p31-knowledge-card-schema.spec.md完成schema v8 Phase-2 knowledge_cards / knowledge_evidence_links / knowledge_events 最小 schema contract
specs/p32-knowledge-card-schema-v8.spec.md完成schema v8 migration：新增 Phase-2 knowledge card 三表、约束、索引、append-only events
specs/p33-knowledge-card-core-api.spec.md完成Phase-2 knowledge card DB core API：Rust types + card/link/event create/read/update/list，不暴露 CLI/MCP/REST
specs/p34-knowledge-card-cli.spec.md完成Phase-2 knowledge card 最小 CLI 管理入口：create/get/list/link/event/events，不接入 MCP/REST/search/context
specs/p35-knowledge-card-mcp-read.spec.md完成Phase-2 knowledge card MCP 只读入口：mempal_knowledge_cards list/get/events，不开放写操作
specs/p36-knowledge-card-backfill-report.spec.md完成Stage-1 knowledge drawer -> Phase-2 card 只读 backfill-plan report；dry-run，不迁移
specs/p37-knowledge-card-backfill-apply.spec.md完成Stage-1 knowledge drawer -> Phase-2 card 显式 backfill apply：默认 dry-run，--execute 创建 cards/links/events
specs/p38-knowledge-card-gate.spec.md完成Phase-2 knowledge card gate：按 role-separated evidence links 评估提升门槛
specs/p39-knowledge-card-lifecycle-cli.spec.md完成Phase-2 knowledge card CLI lifecycle：gate-enforced promote + evidence-backed demote
specs/p40-mcp-knowledge-card-lifecycle.spec.md完成mempal_knowledge_cards 扩展 gate/promote/demote actions
specs/p41-knowledge-card-runtime-boundary.spec.md完成固化 Phase-2 card runtime boundary：cards 已治理，但尚非默认 context/search source
specs/p42-mind-model-completion-audit.spec.md完成MIND-MODEL P42 baseline completion audit + future work 明确化
specs/p43-knowledge-card-retrieval-contract.spec.md完成Phase-2 card retrieval contract：定义 card result + evidence citation 形状，不改默认 runtime 行为
specs/p44-card-context-assembler.spec.md完成mempal context / mempal_context 显式 include_cards：按 P43 contract 注入 active cards + evidence citations
specs/p45-card-linked-evidence-retrieval.spec.md完成mempal knowledge-card retrieve / mempal_knowledge_cards action=retrieve：通过 linked evidence 检索 active cards，不改默认 search
specs/p46-card-context-default-policy.spec.md完成P46 card context default policy：card-aware context 继续 opt-in；未来默认启用必须有 runtime evidence 和 rollback criteria
specs/p47-card-embedding-policy.spec.md完成P47 card embedding policy：暂不加 card-level embeddings；未来实现必须证明 statement-match misses、处理 stale vectors 和 rollback
specs/p48-card-audit-policy.spec.md完成P48 card audit policy：knowledge_events 是 Phase-2 card lifecycle 权威审计；不默认双写 JSONL
specs/p49-research-ingestion-policy.spec.md完成P49 research ingestion policy：research-rs 输出只进 evidence / evidence-backed candidate insights，不可直接定义 dao
specs/p50-evaluator-promotion-policy.spec.md完成P50 evaluator promotion policy：evaluator 只能 advisory，不可绕过 deterministic gates / human review
specs/p51-mind-model-closure-audit.spec.md完成P51 mind model closure audit：确认 P12-P50 baseline 已完成，未来扩展必须开新阶段 spec
specs/p52-phase-3-intake-roadmap.spec.md完成P52 phase 3 intake roadmap：定义 baseline 后新阶段候选轨道与 evidence/rollback/acceptance 入口规则
specs/p53-phase-3-candidate-evidence-audit.spec.md完成P53 phase 3 candidate evidence audit：评估 Phase-3 候选证据，推荐先做 runtime adoption evidence
specs/p54-runtime-adoption-evidence.spec.md完成P54 runtime adoption evidence：schema v9 runtime_adoption_events + DB API
specs/p55-runtime-adoption-cli.spec.md完成P55 runtime adoption CLI：mempal phase3 adoption record/list/stats
specs/p56-card-context-default-gate.spec.md完成P56 card context default gate：read-only Phase-3 gate，不改 include_cards 默认值
specs/p57-card-embedding-evidence-gate.spec.md完成P57 card embedding evidence gate：card embeddings 需 measured miss evidence，未新增 vector schema
specs/p58-evaluator-api-evidence-gate.spec.md完成P58 evaluator API evidence gate：evaluator API 仍 advisory-only，不写 lifecycle
specs/p59-research-adapter-ingestion-contract.spec.md完成P59 research adapter ingestion contract：phase3 research-validate-plan 验证外部 report contract，不自动 ingest
specs/p60-mcp-phase3-runtime-surface.spec.md完成P60 MCP Phase-3 runtime surface：mempal_phase3 暴露 record/list/stats/gate/research_validate_plan
specs/p61-runtime-adoption-recording-protocol.spec.md完成P61 runtime adoption recording protocol：mempal_phase3 action=guidance 定义 used/accepted/rejected/miss/rollback 记录语义
specs/p62-runtime-adoption-cli-guidance.spec.md完成P62 runtime adoption CLI guidance：mempal phase3 adoption guidance 与 MCP guidance 共用记录语义
specs/p63-runtime-adoption-record-helper.spec.md完成P63 runtime adoption record helper：prepare-record / prepare_record 只读生成 record 命令与 payload
specs/p64-runtime-adoption-record-quality-policy.spec.md完成P64 runtime adoption record quality policy：check-record / check_record 只读检查 record 质量
specs/p65-runtime-adoption-review-report.spec.md完成P65 runtime adoption review report：review 只读汇总 adoption evidence
specs/p66-card-context-default-readiness.spec.md完成P66 card context default readiness：readiness 只读判断 include_cards 是否具备未来默认开启资格
specs/p67-research-adapter-ingest.spec.md完成P67 research adapter evidence ingest：research-ingest-plan 显式把 research findings 写入 evidence，candidate insights 仅作为 distill 建议
specs/p68-mcp-research-ingest-plan.spec.md完成P68 MCP research ingest plan：mempal_phase3 action=research_ingest_plan 只读预览 evidence refs + distill 建议
specs/p69-runtime-adoption-checked-record.spec.md完成P69 runtime adoption checked record：record-checked / record_checked 质量门控写入 runtime adoption evidence
specs/p70-self-evolution-completion-audit.spec.md完成P70 self-evolution completion audit：审计完整自进化 agent 系统目标，明确已完成能力与剩余缺口
specs/p71-self-evolution-loop-replay.spec.md完成P71 self-evolution loop replay：CLI E2E replay 证明 research -> evidence -> card promotion -> context -> checked adoption 可闭环
specs/p72-runtime-adoption-capture-helper.spec.md完成P72 runtime adoption capture helper：capture 把 surface/outcome 映射到 checked runtime adoption record
specs/p73-evaluator-advisory-api.spec.md完成P73 evaluator advisory API：phase3 evaluator advise / mempal_phase3 action=evaluator_advise 输出可重放 advisory 建议，不具 lifecycle authority
specs/p74-card-context-default-proposal.spec.md完成P74 card context default-on proposal：default_proposal 结合 P66 readiness 与 rollback criteria，生成只读默认开启提案但不改默认值
specs/p75-self-evolution-completion-audit.spec.md完成P75 self-evolution completion audit：审计 P71-P74 后的完整自进化目标，确认 governed substrate 完成但 autonomous runtime 仍有缺口
specs/p76-spec-completeness-invariant.spec.md完成P76 spec completeness invariant：固化每个 numbered P 必须留下 task spec 与 matching plan 的治理硬规则
specs/p77-live-adoption-instrumentation-boundary.spec.md完成P77 live adoption instrumentation boundary：instrumentation-policy / instrumentation_policy 只读暴露 live instrumentation opt-in 边界，禁止 silent/background capture
specs/p78-card-context-default-runtime-flag.spec.md完成P78 card context default runtime flag：context.include_cards_default 显式默认开关 + phase3 default-control card-context proposal-gated enable / reversible disable
specs/p79-rollback-executor-policy.spec.md完成P79 rollback executor policy：phase3 rollback-control card-context / mempal_phase3 action=rollback_control 将 rollback evidence 转成可执行的默认关闭策略
specs/p80-autonomous-promotion-boundary-audit.spec.md完成P80 autonomous promotion boundary audit：明确 autonomous promotion 当前出界，human-gated lifecycle authority 是最终治理边界
specs/p81-self-evolution-completion-audit.spec.md完成P81 self-evolution completion audit：按 P80 human-gated 边界审计完整自进化 agent 系统目标并确认完成
specs/p82-opt-in-runtime-instrumentation-wrapper.spec.md完成P82 opt-in runtime instrumentation wrapper：mempal phase3 adoption wrap 显式包裹一次 child command，并通过 P72/P69 checked capture 记录 runtime adoption evidence
specs/p83-cognitive-brief.spec.md完成P83 cognitive brief：mempal brief 生成 deterministic citation-first brief，组织 key facts / evidence / cards / uncertainty / next actions，不调用 LLM、不写 DB
specs/p84-multi-agent-cowork-bus.spec.md完成P84 multi-agent cowork bus：agent_id registry + per-agent inbox + CLI send/broadcast/drain/status，支持同项目多 agent 实例隔离通信
specs/p85-mcp-multi-agent-cowork-bus.spec.md完成P85 MCP multi-agent cowork bus：mempal_cowork_bus 暴露 register/list/send/broadcast/drain，让 agent runtime 使用 concrete agent_id 总线
specs/p86-tmux-cowork-transport.spec.md完成P86 tmux cowork transport：transport=tmux 显式使用 tmux send-keys 投递到 concrete agent pane，不经 shell、不 fallback 到 inbox
specs/p87-cowork-bus-event-log.spec.md完成P87 cowork bus event log：events.jsonl append-only 记录 register/send/broadcast/drain/tmux failure，并通过 cowork-events / mempal_cowork_bus action=events 回放
specs/p88-cowork-delivery-ack-status.spec.md完成P88 cowork delivery ack/status：delivery event id 作为 message_id，通过 cowork-deliveries / cowork-ack 和 MCP deliveries / ack 回放 pending/drained/acked/failed
specs/p89-cowork-agent-presence.spec.md完成P89 cowork agent presence：显式 cowork-heartbeat / MCP heartbeat 更新 last_seen_at，cowork-agents / MCP list 推导 online/stale/never_seen
specs/p90-cowork-threads-channels.spec.md完成P90 cowork threads/channels：send/broadcast/channel_send 支持 thread_id / channel 元数据，cowork-channel-set / MCP channel_set 管理 channel membership
specs/p91-tmux-live-peek.spec.md完成P91 tmux live peek：cowork-tmux-peek / MCP tmux_peek 只读捕获已注册 tmux agent pane，不写 events/inbox/registry/DB
specs/p92-multi-agent-runbook.spec.md完成P92 multi-agent cowork runbook：docs/COWORK-RUNBOOK.md + cowork-runbook read-only CLI 固化三方/多方 agent 操作流程
specs/p93-cowork-doctor.spec.md完成P93 cowork doctor：cowork-doctor / MCP doctor 只读诊断 registry、presence、pending deliveries、sessions、channels、可选 tmux probe
specs/p94-cowork-team-session.spec.md完成P94 cowork team session：runtime sessions.json + CLI/MCP session create/list/status，不写 palace.db
specs/p95-cowork-handoff-summary.spec.md完成P95 cowork handoff summary：cowork-handoff / MCP handoff 汇总 sessions、agents、pending deliveries、recent events，支持 thread/channel/session filter
specs/p96-cowork-memory-capture.spec.md完成P96 cowork memory capture：cowork-capture / MCP capture 显式把 handoff summary 写入 evidence drawer，默认 dry-run
specs/p97-maintenance-runbook.spec.md完成P97 maintenance runbook：docs/MAINTENANCE-RUNBOOK.md + maintenance-runbook read-only CLI 固化 research->evidence->knowledge/card->context/adoption/cowork capture 维护流程
specs/p98-release-install-doctor.spec.md完成P98 release install doctor：mempal doctor 只读报告 binary/PATH/schema 兼容性，避免旧 binary 对新 schema 失败时无诊断
specs/p99-mcp-runtime-doctor.spec.md完成P99 MCP runtime doctor：mempal_doctor 暴露 install/schema 诊断与 MCP runtime tool/action 能力清单
specs/p100-guided-maintenance-run.spec.md完成P100 guided maintenance run：mempal maintenance guided-run 只读输出 dream/maintenance 推荐命令与状态计数
specs/p101-cowork-session-close-capture.spec.md完成P101 cowork session close capture：cowork-session-close / MCP session_close 关闭 session，并可显式 dry-run/execute capture
specs/p102-mcp-cognitive-brief.spec.md完成P102 MCP cognitive brief：mempal_brief 向 agent runtime 暴露 deterministic citation-first brief
specs/p103-adoption-analytics.spec.md完成P103 adoption analytics：phase3 adoption analytics / MCP analytics 按 track+feature 汇总 runtime adoption evidence
specs/p104-release-readiness-checklist.spec.md完成P104 release readiness checklist：mempal release-readiness 只读检查 package/docs/spec-plan/runbook/doctor/schema 发布准备状态
specs/p105-mempal-book-zh-cn.spec.md完成P105 mempal book zh-CN：中文 mdBook + Mermaid 渲染 + 每章 agent-spec 写作合约/计划 + 扩展正文，从决策到架构到实际使用
specs/p106-context-distill-signal.spec.md完成P106 context distill signal：mempal context / mempal_context 只读 distill_suggestions——确定性检测 evidence 密集但无 promoted 知识的 field（≥5 evidence 且 0 promoted），给出 distill 建议；不写库、不自动 distill/promote，写入仍走显式 gate
specs/p107-ingest-entrypoint-discoverability.spec.md完成P107 ingest entrypoint discoverability：把 evidence-vs-knowledge ingest 边界做成 first-time agent 下手前可见的 push-型契约——mempal_ingest 工具描述 + IngestRequest knowledge-only 字段 schema doc + 错误文案补救 + MEMORY_PROTOCOL Rule 4；纯文档/可发现性，零 schema/行为/校验变更
specs/p108-peek-cwd-cross-project.spec.md完成P108 peek cwd cross-project：mempal_peek_partner 加可选 cwd + 新 CLI mempal cowork-peek --tool --cwd，支持无 tmux 跨项目读 partner live session；省略 cwd 保持原 current_dir 行为，零 peek_partner/存储变更
specs/p109-cross-project-resume.spec.md完成P109 cross-project resume：mempal projects / mempal_projects 列出所有项目（wing + worktree 路径 + 计数 + 最近活动），mempal resume <fuzzy> / mempal_resume 模糊解析到 wing/路径并返回项目路径 + 最近决策 + in-flight candidate + 下一步；只读、无 embedder、不写库、不改 context；从任意目录"继续 xxx 项目"
specs/p110-public-issue-compatibility.spec.md完成P110 public issue compatibility fixes：修复 GitHub #1-#4（drawer identity source-aware + 12 hex、同批去重/insert bool、Windows ~/ expansion、MCP signed-compatible schema、tunnel_hints always on-wire）
specs/p111-project-ignore-rules.spec.md完成P111 project ignore rules：init / directory ingest 共享 project path-filter，默认尊重 .gitignore + .mempalignore，支持 --ignore-file / --no-gitignore / --no-mempalignore
specs/p112-session-peek.spec.md完成P112 explicit MCP session peek：新增 mempal_session_peek 显式按 tool + cwd 只读读取本地 Claude/Codex session，支持同工具/跨项目场景，同时保持 mempal_peek_partner self-peek 保护不变
specs/p113-public-workspace-crates.spec.md完成P113 public multi-crate workspace split：保留 root mempal CLI 包，同时新增公开可发布的 mempal-embed / mempal-search-core / mempal-agent-memory / mempal-mcp-protocol workspace crates，并通过 legacy facade path 兼容现有 API
specs/p114-coarse-workspace-split.spec.md完成P114 coarse workspace split：新增公开可发布的 mempal-store-sqlite / mempal-runtime / mempal-mcp-server 三个粗粒度 crate，把 SQLite storage、runtime workflows、MCP server wiring 从 root 拆出，同时保留 root CLI 和 legacy facade paths
specs/p115-codex-preamble-noise-strip.spec.md完成P115 Codex runtime preamble strip：strip_codex_rollout_noise 剥离 <INSTRUCTIONS> / <user_instructions> / <environment_context> / <recommended_plugins> / <turn_aborted> wrapper 块（GitHub #10）；CURRENT_NORMALIZE_VERSION 2→3 让 reindex --stale 重拾 PR #7 前的旧 source；is_codex_jsonl 要求至少一条 event_msg/response_item
specs/p116-cowork-pair-delivery-receipts.spec.md完成P116 cowork pair-push delivery receipts：pair 通道每条 push 基于确定性 base 生成唯一 message_id（CoworkPushResponse 返回），push/drain 写有界 receipts event log，mempal cowork-receipts / cowork-status 汇总 pending/drained/lost，cowork-drain --hook-runtime 记录注入 runtime（GitHub #81）
specs/p117-reindex-atomic-replace.spec.md完成P117 atomic reindex replace：embed 先行并验证向量基数，delete/insert 单事务且 closure/COMMIT/ID 冲突失败均回滚；dry-run/real-run 报告并跳过 missing-source 与 Stage-1/Phase-2 knowledge 引用保护的 source，避免 evidence refs 悬空；file-less source 保持不可重归一化
当前 Spec（草稿，未实现）

暂无。

实现计划

  • docs/plans/2026-04-08-p0-implementation.md — P0 关键路径（已完成）

  • docs/plans/2026-04-09-p1-p4-implementation.md — P1-P4（已完成）

  • docs/plans/2026-04-11-p5-implementation.md — P5（已完成）

  • docs/plans/2026-04-13-p6-implementation.md — P6（已完成）

  • docs/plans/2026-04-13-p7-implementation.md — P7（已完成）

  • docs/plans/2026-04-15-p8-implementation.md — P8（已完成）

  • docs/plans/2026-04-17-p9-implementation.md — P9 fact-checker + ingest-lock（已完成）

  • docs/plans/2026-04-23-p10-explicit-tunnels-implementation.md — P10 explicit tunnels（已完成）

  • docs/plans/2026-04-23-p10-normalize-version-implementation.md — P10 normalize-version（已完成）

  • docs/plans/2026-04-23-p11-transcript-noise-strip-implementation.md — P11 transcript noise strip（已完成）

  • docs/plans/2026-04-24-p11-chunk-neighbors-implementation.md — P11 chunk neighbors（已完成）

  • docs/plans/2026-04-24-p11-diary-daily-rollup-implementation.md — P11 diary daily rollup（已完成）

  • docs/plans/2026-04-21-p12-implementation.md — P12 mind-model bootstrap（已完成）

  • docs/plans/2026-04-23-p13a-implementation.md — P13A wake-up statement（已完成）

  • docs/plans/2026-04-23-p13b-implementation.md — P13B bootstrap ingest identity parity（已完成）

  • docs/plans/2026-04-24-p14-context-assembler-implementation.md — P14 mind-model runtime context assembler（已完成）

  • docs/plans/2026-04-24-p15-mcp-context-implementation.md — P15 mempal_context MCP tool（已完成）

  • docs/plans/2026-04-24-p16-context-skill-guidance-implementation.md — P16 context-guided skill selection protocol（已完成）

  • docs/plans/2026-04-24-p17-knowledge-lifecycle-implementation.md — P17 bootstrap knowledge lifecycle CLI（已完成）

  • docs/plans/2026-04-24-p18-knowledge-distill-implementation.md — P18 bootstrap knowledge distill CLI（已完成）

  • docs/plans/2026-04-24-p19-lifecycle-ref-validation-implementation.md — P19 lifecycle evidence ref validation（已完成）

  • docs/plans/2026-04-25-p20-promotion-gate-policy-implementation.md — P20 promotion gate policy（已完成）

  • docs/plans/2026-04-25-p21-mcp-knowledge-gate-implementation.md — P21 MCP knowledge gate（已完成）

  • docs/plans/2026-04-25-p22-mcp-knowledge-distill-implementation.md — P22 MCP knowledge distill（已完成）

  • docs/plans/2026-04-26-p23-mcp-knowledge-lifecycle-implementation.md — P23 MCP knowledge lifecycle（已完成）

  • docs/plans/2026-04-26-p24-anchor-publication-implementation.md — P24 anchor publication CLI（已完成）

  • docs/plans/2026-04-26-p25-mcp-anchor-publication-implementation.md — P25 MCP anchor publication（已完成）

  • docs/plans/2026-04-26-p26-dao-tian-runtime-budget-implementation.md — P26 dao_tian runtime budget（已完成）

  • docs/plans/2026-04-26-p27-knowledge-policy-surface-implementation.md — P27 knowledge policy surface（已完成）

  • docs/plans/2026-04-26-p28-field-taxonomy-surface-implementation.md — P28 field taxonomy surface（已完成）

  • docs/plans/2026-04-26-p29-wake-up-context-boundary-implementation.md — P29 wake-up/context boundary（已完成）

  • docs/plans/2026-04-27-p30-knowledge-card-storage-boundary-implementation.md — P30 knowledge card storage boundary（已完成）

  • docs/plans/2026-04-27-p31-knowledge-card-schema-spec.md — P31 knowledge card schema spec（已完成）

  • docs/plans/2026-04-27-p32-knowledge-card-schema-v8-implementation.md — P32 knowledge card schema v8（已完成）

  • docs/plans/2026-04-27-p33-knowledge-card-core-api-implementation.md — P33 knowledge card core API（已完成）

  • docs/plans/2026-04-27-p34-knowledge-card-cli-implementation.md — P34 knowledge card CLI（已完成）

  • docs/plans/2026-04-27-p35-knowledge-card-mcp-read-implementation.md — P35 knowledge card MCP read（已完成）

  • docs/plans/2026-04-27-p36-knowledge-card-backfill-report-implementation.md — P36 knowledge card backfill report（已完成）

  • docs/plans/2026-04-27-p37-knowledge-card-backfill-apply-implementation.md — P37 knowledge card backfill apply（已完成）

  • docs/plans/2026-04-27-p38-p42-knowledge-card-runtime-implementation.md — P38-P42 knowledge card runtime baseline（已完成）

  • docs/plans/2026-04-28-p43-knowledge-card-retrieval-contract.md — P43 knowledge card retrieval contract（已完成）

  • docs/plans/2026-04-28-p44-card-context-assembler.md — P44 card-aware context assembler（已完成）

  • docs/plans/2026-04-28-p45-card-linked-evidence-retrieval.md — P45 card linked-evidence retrieval（已完成）

  • docs/plans/2026-04-28-p46-card-context-default-policy.md — P46 card context default policy（已完成）

  • docs/plans/2026-04-28-p47-card-embedding-policy.md — P47 card embedding policy（已完成）

  • docs/plans/2026-04-29-p48-card-audit-policy.md — P48 card audit policy（已完成）

  • docs/plans/2026-04-29-p49-research-ingestion-policy.md — P49 research ingestion policy（已完成）

  • docs/plans/2026-04-29-p50-evaluator-promotion-policy.md — P50 evaluator promotion policy（已完成）

  • docs/plans/2026-04-29-p51-mind-model-closure-audit.md — P51 mind model closure audit（已完成）

  • docs/plans/2026-05-01-p52-phase-3-intake-roadmap.md — P52 phase 3 intake roadmap（已完成）

  • docs/plans/2026-05-02-p53-phase-3-candidate-evidence-audit.md — P53 phase 3 candidate evidence audit（已完成）

  • docs/plans/2026-05-02-p54-runtime-adoption-evidence.md — P54 runtime adoption evidence（已完成）

  • docs/plans/2026-05-02-p55-runtime-adoption-cli.md — P55 runtime adoption CLI（已完成）

  • docs/plans/2026-05-02-p56-card-context-default-gate.md — P56 card context default gate（已完成）

  • docs/plans/2026-05-02-p57-card-embedding-evidence-gate.md — P57 card embedding evidence gate（已完成）

  • docs/plans/2026-05-02-p58-evaluator-api-evidence-gate.md — P58 evaluator API evidence gate（已完成）

  • docs/plans/2026-05-02-p59-research-adapter-ingestion-contract.md — P59 research adapter ingestion contract（已完成）

  • docs/plans/2026-05-05-p60-mcp-phase3-runtime-surface.md — P60 MCP Phase-3 runtime surface（已完成）

  • docs/plans/2026-05-10-p61-runtime-adoption-recording-protocol.md — P61 runtime adoption recording protocol（已完成）

  • docs/plans/2026-05-12-p62-runtime-adoption-cli-guidance.md — P62 runtime adoption CLI guidance（已完成）

  • docs/plans/2026-05-12-p63-runtime-adoption-record-helper.md — P63 runtime adoption record helper（已完成）

  • docs/plans/2026-05-13-p64-runtime-adoption-record-quality-policy.md — P64 runtime adoption record quality policy（已完成）

  • docs/plans/2026-05-13-p65-runtime-adoption-review-report.md — P65 runtime adoption review report（已完成）

  • docs/plans/2026-05-13-p66-card-context-default-readiness.md — P66 card context default readiness（已完成）

  • docs/plans/2026-05-13-p67-research-adapter-ingest.md — P67 research adapter evidence ingest（已完成）

  • docs/plans/2026-05-13-p68-mcp-research-ingest-plan.md — P68 MCP research ingest plan（已完成）

  • docs/plans/2026-05-13-p69-runtime-adoption-checked-record.md — P69 runtime adoption checked record（已完成）

  • docs/plans/2026-05-13-p70-self-evolution-completion-audit.md — P70 self-evolution completion audit（已完成）

  • docs/plans/2026-05-13-p71-self-evolution-loop-replay.md — P71 self-evolution loop replay（已完成）

  • docs/plans/2026-05-13-p72-runtime-adoption-capture-helper.md — P72 runtime adoption capture helper（已完成）

  • docs/plans/2026-05-13-p73-evaluator-advisory-api.md — P73 evaluator advisory API（已完成）

  • docs/plans/2026-05-13-p74-card-context-default-proposal.md — P74 card context default-on proposal（已完成）

  • docs/plans/2026-05-13-p75-self-evolution-completion-audit.md — P75 self-evolution completion audit（已完成）

  • docs/plans/2026-05-13-p76-spec-completeness-invariant.md — P76 spec completeness invariant（已完成）

  • docs/plans/2026-05-13-p77-live-adoption-instrumentation-boundary.md — P77 live adoption instrumentation boundary（已完成）

  • docs/plans/2026-05-13-p78-card-context-default-runtime-flag.md — P78 card context default runtime flag（已完成）

  • docs/plans/2026-05-13-p79-rollback-executor-policy.md — P79 rollback executor policy（已完成）

  • docs/plans/2026-05-13-p80-autonomous-promotion-boundary-audit.md — P80 autonomous promotion boundary audit（已完成）

  • docs/plans/2026-05-13-p81-self-evolution-completion-audit.md — P81 self-evolution completion audit（已完成）

  • docs/plans/2026-05-25-p82-opt-in-runtime-instrumentation-wrapper.md — P82 opt-in runtime instrumentation wrapper（已完成）

  • docs/plans/2026-05-25-p83-cognitive-brief.md — P83 cognitive brief（已完成）

  • docs/plans/2026-05-25-p84-multi-agent-cowork-bus.md — P84 multi-agent cowork bus（已完成）

  • docs/plans/2026-05-25-p85-mcp-multi-agent-cowork-bus.md — P85 MCP multi-agent cowork bus（已完成）

  • docs/plans/2026-05-25-p86-tmux-cowork-transport.md — P86 tmux cowork transport（已完成）

  • docs/plans/2026-05-25-p87-cowork-bus-event-log.md — P87 cowork bus event log（已完成）

  • docs/plans/2026-05-25-p88-cowork-delivery-ack-status.md — P88 cowork delivery ack/status（已完成）

  • docs/plans/2026-05-25-p89-cowork-agent-presence.md — P89 cowork agent presence（已完成）

  • docs/plans/2026-05-25-p90-cowork-threads-channels.md — P90 cowork threads/channels（已完成）

  • docs/plans/2026-05-25-p91-tmux-live-peek.md — P91 tmux live peek（已完成）

  • docs/plans/2026-05-26-p92-multi-agent-runbook.md — P92 multi-agent cowork runbook（已完成）

  • docs/plans/2026-05-26-p93-cowork-doctor.md — P93 cowork doctor（已完成）

  • docs/plans/2026-05-26-p94-cowork-team-session.md — P94 cowork team session（已完成）

  • docs/plans/2026-05-26-p95-cowork-handoff-summary.md — P95 cowork handoff summary（已完成）

  • docs/plans/2026-05-26-p96-cowork-memory-capture.md — P96 cowork memory capture（已完成）

  • docs/plans/2026-05-26-p97-maintenance-runbook.md — P97 maintenance runbook（已完成）

  • docs/plans/2026-05-26-p98-release-install-doctor.md — P98 release install doctor（已完成）

  • docs/plans/2026-05-26-p99-mcp-runtime-doctor.md — P99 MCP runtime doctor（已完成）

  • docs/plans/2026-05-26-p100-guided-maintenance-run.md — P100 guided maintenance run（已完成）

  • docs/plans/2026-05-26-p101-cowork-session-close-capture.md — P101 cowork session close capture（已完成）

  • docs/plans/2026-05-26-p102-mcp-cognitive-brief.md — P102 MCP cognitive brief（已完成）

  • docs/plans/2026-05-26-p103-adoption-analytics.md — P103 adoption analytics（已完成）

  • docs/plans/2026-05-26-p104-release-readiness-checklist.md — P104 release readiness checklist（已完成）

  • docs/plans/2026-05-28-p105-mempal-book-zh-cn.md — P105 mempal book zh-CN（已完成）

  • docs/plans/2026-06-04-p106-context-distill-signal.md — P106 context distill signal（已完成）

  • docs/plans/2026-06-09-p107-ingest-entrypoint-discoverability.md — P107 ingest entrypoint discoverability（已完成）

  • docs/plans/2026-06-17-p108-peek-cwd-cross-project.md — P108 peek cwd cross-project（已完成）

  • docs/plans/2026-06-22-p109-cross-project-resume.md — P109 cross-project resume（已完成）

  • docs/plans/2026-07-02-p110-public-issue-compatibility.md — P110 public issue compatibility fixes（已完成）

  • docs/plans/2026-07-06-p111-project-ignore-rules.md — P111 project ignore rules（已完成）

  • docs/plans/2026-07-07-p112-session-peek.md — P112 explicit MCP session peek（已完成）

  • docs/plans/2026-07-08-p113-public-workspace-crates.md — P113 public multi-crate workspace split（已完成）

  • docs/plans/2026-07-09-p114-coarse-workspace-split.md — P114 coarse workspace split（已完成）

  • docs/plans/2026-07-26-p115-codex-preamble-noise-strip.md — P115 Codex runtime preamble strip + normalize version bump（已完成）

  • docs/plans/2026-07-26-p116-cowork-pair-delivery-receipts.md — P116 cowork pair-push delivery receipts（已完成）

  • docs/plans/2026-08-18-p117-reindex-atomic-replace.md — P117 atomic reindex replace + dry-run feasibility report（已完成）

Spec 使用方式
agent-spec parse specs/p6-cowork-peek-and-decide.spec.md
agent-spec lint specs/p6-cowork-peek-and-decide.spec.md --min-score 0.7

关键架构约束

  • 存储：SQLite + sqlite-vec，单文件 ~/.mempal/palace.db，schema v9

  • 嵌入：model2vec-rs 默认（potion-multilingual-128M, 256d），可选 ort (ONNX) 通过 onnx feature flag

  • 搜索：BM25 (FTS5) + 向量 + RRF 融合混合检索

  • AAAK 是输出格式化器：不被 ingest 或 search 依赖

  • 数据永远 raw 存储：drawers 表存原文，向量索引在 drawer_vectors 表（维度动态）

  • 搜索结果强制带引用：SearchResult 包含 source_file、drawer_id、tunnel_hints

  • 知识图谱：triples 表已激活（手动 CRUD），支持时态验证

  • 隧道：动态跨 Wing 链接发现，内联到搜索结果

  • 自描述协议：MEMORY_PROTOCOL 嵌入 MCP ServerInfo.instructions，17 条规则

MCP 工具（25 个）

工具作用
mempal_status状态 + 协议 + AAAK spec
mempal_doctorrelease/install + MCP runtime diagnostics：报告 binary/PATH/schema 兼容性和 required MCP tool/action 能力清单（P99）
mempal_search混合检索（BM25 + 向量 + RRF + tunnel hints）+ AAAK 结构化 signals（P7）
mempal_contextmind-model runtime context：按 dao_tian -> dao_ren -> shu -> qi 组装指导性 context pack；dao_tian_limit 默认 1；用于辅助 workflow/skill/tool 选择但不自动执行（P15/P16/P26/P44）
mempal_briefdeterministic citation-first cognitive brief：summary/key facts/evidence/cards/uncertainty/next actions，不调用 LLM、不写 DB（P102）
mempal_field_taxonomyread-only Stage-1 field taxonomy guidance：推荐 field 值但不限制自定义字段（P28）
mempal_knowledge_distill从 existing evidence drawer refs 创建 candidate dao_ren / qi knowledge drawer（P22）
mempal_knowledge_policyread-only Stage-1 promotion policy：列出 dao_tian/dao_ren/shu/qi 提升阈值（P27）
mempal_knowledge_gateread-only promotion readiness check：评估 knowledge drawer 是否满足提升门槛（P21）
mempal_knowledge_promotegate-enforced knowledge lifecycle promotion（P23）
mempal_knowledge_demoteevidence-backed knowledge demotion / retirement（P23）
mempal_knowledge_publish_anchormetadata-only outward anchor publication（P25）
mempal_knowledge_cardsPhase-2 knowledge card list/get/events/gate/promote/demote/retrieve；retrieve 通过 linked evidence 返回 active cards（P35/P40/P45）
mempal_phase3Phase-3 runtime adoption evidence：guidance/instrumentation_policy/prepare_record/capture/evaluator_advise/default_proposal/check_record/record_checked/review/readiness/analytics/record/list/stats/gate/research_validate_plan/research_ingest_plan（P60/P61/P63/P64/P65/P66/P68/P69/P72/P73/P74/P77/P103）
mempal_ingest写记忆（支持 dry_run；P9-B 暴露 lock_wait_ms）；默认写 evidence drawer，knowledge-only 字段被拒并引导至 mempal_knowledge_distill（P107）
mempal_deletesoft-delete（+ audit）
mempal_taxonomyWing/Room 路由关键词管理
mempal_kg知识图谱三元组（add/query/invalidate）
mempal_tunnels跨 Wing 链接发现
mempal_projects列出所有项目（wing + worktree 路径 + 计数 + 最近活动），从任意目录可用（P109）
mempal_resume按模糊名解析项目并返回路径 + 最近决策 + in-flight candidate + 下一步（P109）
mempal_peek_partner读 partner agent 当前 session（live，不存储）；可选 cwd 跨项目读（P108，对应 CLI mempal cowork-peek）
mempal_cowork_push主动投递 ephemeral handoff 到 partner inbox（at-next-submit 交付）
mempal_cowork_bus多 agent concrete agent_id 总线：register/list/send/broadcast/drain/events/deliveries/ack/heartbeat/channel_set/channel_list/channel_send/tmux_peek/doctor/session_create/session_list/session_status/session_close/handoff/capture，支持 opt-in transport=tmux、event replay、delivery ack/status、presence、group channels、read-only tmux pane peek、诊断、session、handoff summary、显式 handoff-to-evidence capture（P85/P86/P87/P88/P89/P90/P91/P93/P94/P95/P96/P101）
mempal_fact_check离线矛盾检测（SimilarNameConflict / RelationContradiction / StaleFact）—— P9

mempal 检索纪律

当 agent 回答本项目的历史决策、实现细节、bug 成因、架构理由、或“为什么/怎么工作”类问题时：

  1. 每个 session 先调一次 mempal_status，再决定是否使用 wing / room filter。

  2. 对项目事实优先使用 mempal_search，不要只靠 repo grep、当前对话记忆或常识猜测。

  3. 在本仓库内，只要 mempal_status 已确认存在 wing="mempal"，默认先用 wing="mempal" 缩小范围；只有用户明确要求跨项目 / 全局搜索时才放宽。

  4. 历史决策、设计理由、bug 成因这类问题，第一轮检索默认使用简短英文语义 query，且 top_k=2；只有证据不足时才逐步放大到 top_k=3-4 或放宽 query。

  5. 如果 MCP 客户端提示 Large response / Large MCP response，优先重试更窄的 query、加 wing / room、或降低 top_k；不要直接消费一大段 raw content。

  6. 显式消费 mempal_search 返回的结构化 signals，而不是只读 content：

    • 决策问题：优先 flags 包含 DECISION 的结果

    • 实现 / bug / 架构问题：优先 flags 包含 TECHNICAL 的结果

    • 同等条件下优先处理 importance_stars 更高的结果

    • 用 entities 和 topics 缩小歧义结果集

  7. 将 content 视为 raw text；不要期待或解析 mempal_search 返回 AAAK 格式文本。

  8. 基于 mempal 结果作答时，必须引用 drawer_id 和 source_file。

  9. 如果没有找到高信号结果，要明确说明“没找到足够证据”，然后扩大查询范围；不要猜。

代码结构

Cargo workspace，root package 仍是 mempal，并继续提供 cargo install mempal 的 CLI binary。P113/P114 已把可复用边界拆成公开 workspace crates；root crate 现在主要负责 CLI、REST entrypoint、package metadata 和 legacy facade paths。

Cargo.toml                         # package + workspace root；root package name 仍为 mempal
src/
├── main.rs                        # CLI 入口（search/context/brief/knowledge/phase3/cowork 等）
├── lib.rs                         # root facade；保留 mempal::* legacy paths
├── api/                           # REST API（feature-gated `rest`），调用 root facade/runtime
├── core/                          # facade：db/config/phase3/utils/protocol/types/anchor
├── embed/                         # facade：mempal_runtime::embed
├── mcp/                           # facade：mempal_mcp_server::MempalMcpServer
└── *.rs / */mod.rs                # facade：re-export mempal-runtime modules
crates/
├── mempal-embed/                  # public Embedder / EmbedderFactory + API/model2vec/ONNX implementations
├── mempal-search-core/            # public FTS5 escaping + RRF rank fusion primitives
├── mempal-agent-memory/           # public memory domain types + anchor helpers
├── mempal-mcp-protocol/           # public MEMORY_PROTOCOL text
├── mempal-store-sqlite/           # public SQLite schema v9 + Database + migrations + FTS/sqlite-vec/KG/tunnels/cards/adoption tables
├── mempal-runtime/                # public ingest/search/context/brief/knowledge/factcheck/projects/cowork/doctor/AAAK workflows
└── mempal-mcp-server/             # public rmcp server + tool request/response wiring

mempal::core::db、mempal::core::types、mempal::core::anchor、 mempal::core::protocol、mempal::embed、mempal::search、mempal::ingest、 mempal::context、mempal::mcp::MempalMcpServer 等都是兼容 facade， re-export 对应 workspace crates。新增子 crate 都是公开可发布 package；root mempal 用 path + version dependency 连接。

代码规范

  • Edition 2024

  • #![warn(clippy::all)]

  • 错误处理：anyhow（应用层）+ thiserror（库层）

  • 异步：tokio，features=["full"]

  • 不用 .unwrap()，用 ? 或 .expect("reason")

  • 每次 commit 后：调 mempal_ingest 存决策记忆（Rule 4）

Auto-Dream 集成

当 Claude Code 执行 auto-dream 或手动 dream 时：

  1. 验证：调 mempal_search 核实正在整理的事实是否与 mempal 记忆一致

  2. 保存：将整理后的高价值洞察存到 mempal（mempal_ingest，importance >= 3）

  3. 解矛盾：MEMORY.md 与 mempal drawer 矛盾时，以 mempal 为准（mempal 有出处引用）

  4. 写日记：将 dream 摘要存为 agent diary（wing="agent-diary", room="claude"）

  5. 清理 KG：检查 triples 中是否有过期关系需要 invalidate

Dream 是 mempal 的"REM 睡眠"——短期 session 记忆被整理为长期项目记忆。

Known Limitations / Operational Notes

以下是 0.3.0 已知、来自真实 E2E 的跨系统约束，和 mempal 代码无关但会直接影响使用体验，记录在此避免重复踩坑：

  1. mempal cowork-install-hooks 写两件 Claude 侧制品：.claude/hooks/user-prompt-submit.sh（脚本）+ .claude/settings.json 下的 hooks.UserPromptSubmit 条目（注册）。Claude Code 不按文件名约定自动发现脚本，两件都必须有hook 才会 fire。install-hooks 已自动处理 + 自愈 stale 条目；请勿手工移除其中任一。

  2. Codex 侧依赖 codex_hooks feature flag：shipped codex-cli ≤ 0.120.0 该 flag 处于 "under development" 且默认 false，此时 Codex runtime 完全忽略 ~/.codex/hooks.json。install-hooks 检测到会打印 warning + 激活命令 codex features enable codex_hooks。

  3. Codex TUI 进程启动时一次性缓存 config：改完 config.toml 或 hooks.json（含 feature flag / install-hooks）后，必须完全退出并重启 Codex TUI；已在跑的进程拿不到新配置。

  4. Claude Code 的 MCP server 是 session startup spawn：cargo install 升级 mempal binary 后，Claude Code 还在用旧 MCP server 进程，不认识新加的工具（如 mempal_cowork_push）。升级后重启 Claude Code，MCP server 会 respawn 到新 binary。

  5. mempal_cowork_push 依赖 MCP ClientInfo.name 被识别为 Claude/Codex 家族之一（src/cowork/peek.rs Tool::from_str_ci）：caller_tool 推断基于 MCP ClientInfo.name，是 self-push 拒绝和 InboxMessage.from 填写的前提。当前识别名单（0.3.1）：claude / claude-code / claude_code / codex / codex-cli / codex_cli / codex-tui / codex-mcp-client（Codex 实际发送的字符串，源自 codex-rs/codex-mcp/src/mcp_connection_manager.rs:1458）。其它 MCP 客户端名字不在此列表时即使显式传 target_tool 也会被拒；这不是 by-design scope 限制，只是当前只覆盖 Claude↔Codex pair，遇到新家族继续扩名单即可。

453 files · 436 not served here

Advantages

  • Hybrid search combines BM25 and vector semantic search for improved retrieval. evidence: README.md
  • Self-describing protocol allows agents to learn interaction rules automatically. evidence: README.md
  • Per-source advisory locking prevents race conditions during concurrent agent ingestion. evidence: README.md

Limitations

Security

Risk level: Low risk

This brain runs

Hooks (2)

  • .claude/settings.json (PostToolUse): if echo "$TOOL_INPUT" | grep -q 'git commit'; then echo 'MEMPAL REMINDER: You just committed code. Call mempal_ingest to save the decision context (what was built, why, what was considered). Rule 4: SAVE AFTER DECISIONS.'; fi
  • .claude/settings.json (UserPromptSubmit): bash .claude/hooks/user-prompt-submit.sh

MCP servers (1)

  • .mcp.json (mempal): mempal serve --mcp

Agent instructions that run or fetch something (22)

  • AGENTS.md: Rust 实现的 coding agent 项目记忆工具。单二进制，`cargo install mempal`，10 秒内带出处找回历史决策。
  • AGENTS.md: | Spec | 状态 | 范围 | |------|------|------| | `specs/p0-core-scaffold.spec.md` | 完成 | workspace 骨架 + SQLite schema | | `specs/p0-embed-trait.spec.md` | 完成 | Embedder trait（model2vec 默认 + ort 可选） | | `specs/p0-ingest.spec.md` | 完成 | 导入管道（格式检测/归一化/分块/存储） | | `specs/p0-search-cli.spec.md` …[+7715 chars]
  • AGENTS.md: `docs/plans/2026-05-26-p98-release-install-doctor.md` — P98 release install doctor（已完成）
  • AGENTS.md: `docs/plans/2026-05-26-p100-guided-maintenance-run.md` — P100 guided maintenance run（已完成）
  • AGENTS.md: `docs/plans/2026-08-18-p117-reindex-atomic-replace.md` — P117 atomic reindex replace + dry-run feasibility report（已完成）
  • AGENTS.md: | 工具 | 作用 | |------|------| | `mempal_status` | 状态 + 协议 + AAAK spec | | `mempal_doctor` | release/install + MCP runtime diagnostics：报告 binary/PATH/schema 兼容性和 required MCP tool/action 能力清单（P99） | | `mempal_search` | 混合检索（BM25 + 向量 + RRF + tunnel hints）+ AAAK 结构化 signals（P7） | | `mempa …[+2688 chars]
  • AGENTS.md: Cargo workspace，root package 仍是 `mempal`，并继续提供 `cargo install mempal` 的 CLI binary。P113/P114 已把可复用边界拆成公开 workspace crates；root crate 现在主要负责 CLI、REST entrypoint、package metadata 和 legacy facade paths。
  • AGENTS.md: **`mempal cowork-install-hooks` 写两件 Claude 侧制品**：`.claude/hooks/user-prompt-submit.sh`（脚本）+ `.claude/settings.json` 下的 `hooks.UserPromptSubmit` 条目（注册）。Claude Code 不按文件名约定自动发现脚本，两件**都必须有**hook 才会 fire。`install-hooks` 已自动处理 + 自愈 stale 条目；请勿手工移除其中任一。
  • AGENTS.md: **Codex 侧依赖 `codex_hooks` feature flag**：shipped `codex-cli ≤ 0.120.0` 该 flag 处于 "under development" 且默认 `false`，此时 Codex runtime 完全忽略 `~/.codex/hooks.json`。`install-hooks` 检测到会打印 warning + 激活命令 `codex features enable codex_hooks`。
  • AGENTS.md: **Codex TUI 进程启动时一次性缓存 config**：改完 `config.toml` 或 `hooks.json`（含 feature flag / install-hooks）后，必须完全退出并重启 Codex TUI；已在跑的进程拿不到新配置。
  • AGENTS.md: **Claude Code 的 MCP server 是 session startup spawn**：`cargo install` 升级 mempal binary 后，Claude Code 还在用旧 MCP server 进程，**不认识新加的工具**（如 `mempal_cowork_push`）。升级后重启 Claude Code，MCP server 会 respawn 到新 binary。
  • CLAUDE.md: Rust 实现的 coding agent 项目记忆工具。单二进制，`cargo install mempal`，10 秒内带出处找回历史决策。
  • CLAUDE.md: | Spec | 状态 | 范围 | |------|------|------| | `specs/p0-core-scaffold.spec.md` | 完成 | workspace 骨架 + SQLite schema | | `specs/p0-embed-trait.spec.md` | 完成 | Embedder trait（model2vec 默认 + ort 可选） | | `specs/p0-ingest.spec.md` | 完成 | 导入管道（格式检测/归一化/分块/存储） | | `specs/p0-search-cli.spec.md` …[+7715 chars]
  • CLAUDE.md: `docs/plans/2026-05-26-p98-release-install-doctor.md` — P98 release install doctor（已完成）
  • CLAUDE.md: `docs/plans/2026-05-26-p100-guided-maintenance-run.md` — P100 guided maintenance run（已完成）
  • CLAUDE.md: `docs/plans/2026-08-18-p117-reindex-atomic-replace.md` — P117 atomic reindex replace + dry-run feasibility report（已完成）
  • CLAUDE.md: | 工具 | 作用 | |------|------| | `mempal_status` | 状态 + 协议 + AAAK spec | | `mempal_doctor` | release/install + MCP runtime diagnostics：报告 binary/PATH/schema 兼容性和 required MCP tool/action 能力清单（P99） | | `mempal_search` | 混合检索（BM25 + 向量 + RRF + tunnel hints）+ AAAK 结构化 signals（P7） | | `mempa …[+2688 chars]
  • CLAUDE.md: Cargo workspace，root package 仍是 `mempal`，并继续提供 `cargo install mempal` 的 CLI binary。P113/P114 已把可复用边界拆成公开 workspace crates；root crate 现在主要负责 CLI、REST entrypoint、package metadata 和 legacy facade paths。
  • CLAUDE.md: **`mempal cowork-install-hooks` 写两件 Claude 侧制品**：`.claude/hooks/user-prompt-submit.sh`（脚本）+ `.claude/settings.json` 下的 `hooks.UserPromptSubmit` 条目（注册）。Claude Code 不按文件名约定自动发现脚本，两件**都必须有**hook 才会 fire。`install-hooks` 已自动处理 + 自愈 stale 条目；请勿手工移除其中任一。
  • CLAUDE.md: **Codex 侧依赖 `codex_hooks` feature flag**：shipped `codex-cli ≤ 0.120.0` 该 flag 处于 "under development" 且默认 `false`，此时 Codex runtime 完全忽略 `~/.codex/hooks.json`。`install-hooks` 检测到会打印 warning + 激活命令 `codex features enable codex_hooks`。
  • CLAUDE.md: **Codex TUI 进程启动时一次性缓存 config**：改完 `config.toml` 或 `hooks.json`（含 feature flag / install-hooks）后，必须完全退出并重启 Codex TUI；已在跑的进程拿不到新配置。
  • CLAUDE.md: **Claude Code 的 MCP server 是 session startup spawn**：`cargo install` 升级 mempal binary 后，Claude Code 还在用旧 MCP server 进程，**不认识新加的工具**（如 `mempal_cowork_push`）。升级后重启 Claude Code，MCP server 会 respawn 到新 binary。
  • Low risk: scripts-present (.claude/hooks/user-prompt-submit.sh)

Attribution and licence

First committed by
GitHub avatar of ZhangHanDongZhangHanDong
Publisher
Alex (Community)
Source
ZhangHanDong/mempal · commit 9ed705d
Licence
MIT License (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
ZhangHanDong, LiuZiqi-dual, TigerInYourDream, jolestar, ryushione

AutoGineer is not affiliated with or endorsed by ZhangHanDong.

Install from source

436 of its files are not served here, so there is no ZIP. ZhangHanDong/mempal at 9ed705d