### Install Mempal CLI with REST Support

Source: https://github.com/zhanghandong/mempal/blob/main/README.md

Install the mempal CLI with REST support enabled.

```bash
cargo install --path crates/mempal-cli --locked --features rest
```

--------------------------------

### Install Mempal CLI

Source: https://github.com/zhanghandong/mempal/blob/main/README.md

Install the mempal command-line interface using cargo.

```bash
cargo install --path crates/mempal-cli --locked
```

--------------------------------

### Example Identity File Content

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

An example of the content for the ~/.mempal/identity.txt file, defining an AI agent's role, focus, and working style.

```text
Role: Rust backend engineer at Acme.
Current focus: auth rewrite, Clerk migration.
Working style: small reversible edits, verify before asserting.
```

--------------------------------

### Mempal Configuration Example (ONNX Embed)

Source: https://github.com/zhanghandong/mempal/blob/main/README.md

Example TOML configuration for mempal, specifying the ONNX embedder backend.

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

--------------------------------

### Start REST Server

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Builds and starts the mempal REST API server, which listens on `127.0.0.1:3080`. CORS is restricted to localhost origins.

```APIDOC
## REST Server

Build with `--features rest` to enable REST:

```bash
mempal serve
```

With REST enabled:

- MCP still runs over stdio
- REST listens on `127.0.0.1:3080`
- CORS only allows localhost origins
```

--------------------------------

### Install Coworking Hooks

Source: https://github.com/zhanghandong/mempal/blob/main/README.md

Install the necessary hooks for agent coworking. Run this command once per repository at the repo root. The `--global-codex` flag is optional.

```bash
mempal cowork-install-hooks --global-codex
```

--------------------------------

### Mempal Configuration Example (Default Embed)

Source: https://github.com/zhanghandong/mempal/blob/main/README.md

Example TOML configuration for mempal, specifying the default embedder.

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

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

--------------------------------

### Mempal Command: Install Cowork Hooks

Source: https://github.com/zhanghandong/mempal/blob/main/README.md

Install UserPromptSubmit hooks for Claude Code, with optional Codex merge.

```bash
mempal cowork-install-hooks [--global-codex]
```

--------------------------------

### Mempal Configuration Example (API Embed)

Source: https://github.com/zhanghandong/mempal/blob/main/README.md

Example TOML configuration for mempal, specifying an external API embedder.

```toml
# External API
[embed]
backend = "api"
api_endpoint = "http://localhost:11434/api/embeddings"
api_model = "nomic-embed-text"
```

--------------------------------

### Mempal Command: Serve

Source: https://github.com/zhanghandong/mempal/blob/main/README.md

Start the mempal MCP server, with optional REST support.

```bash
mempal serve [--mcp]
```

--------------------------------

### Start Mempal REST Server

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Builds and starts the mempal REST server with the `--features rest` flag. The server listens on localhost:3080 and allows CORS only from localhost origins.

```bash
mempal serve
```

--------------------------------

### Mempal Cowork Hooks Installation

Source: https://github.com/zhanghandong/mempal/blob/main/AGENTS.md

The `mempal cowork-install-hooks` command installs two artifacts on the Claude side: a script (`.claude/hooks/user-prompt-submit.sh`) and a registration entry in settings (`.claude/settings.json`). Both are necessary for the hook to fire, and the command handles automatic processing and self-healing of stale entries.

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

--------------------------------

### Actual Reindex Completion Output Example

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-23-p10-normalize-version-implementation.md

Example of the output upon successful completion of a reindex operation, detailing the number of sources and drawers processed, files and chunks written, and any skipped items.

```text
reindex complete: processed 2 sources, 5 drawers selected, 5 chunks written, skipped 0 missing-source drawers
```

--------------------------------

### Setup Test Environment for Codex Session

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-13-p6-implementation.md

Creates a directory and a JSONL file to simulate a codex session with a specific timestamp and content. This is used to test the `peek_partner` function's ability to handle different codex sessions.

```rust
    // Add a second codex session for a different cwd, newer by touch.
    let other_dir = home.join(".codex/sessions/2026/04/14");
    fs::create_dir_all(&other_dir).unwrap();
    fs::write(
        other_dir.join("rollout-2026-04-14T12-00-00-other.jsonl"),
        r#"{"timestamp":"2026-04-14T12:00:00Z","type":"session_meta","payload":{"id":"other","timestamp":"2026-04-14T12:00:00Z","cwd":"/tmp/project-b-xyz","originator":"codex-tui"}}
{"timestamp":"2026-04-14T12:00:10Z","type":"response_item","payload":{"type":"message","role":"user","content":[{"type":"input_text","text":"should not appear"}]}}
"#,
    )
    .unwrap();

    let req = PeekRequest {
        tool: Tool::Codex,
        limit: 30,
        since: None,
        cwd: cwd_a,
        caller_tool: Some(Tool::Claude),
        home_override: Some(home),
    };
    let resp = peek_partner(req).expect("peek");
    let path_str = resp.session_path.unwrap();
    assert!(path_str.contains("project-a"));
    for m in &resp.messages {
        assert!(!m.text.contains("should not appear"));
    }
}
```

--------------------------------

### Get rmcp initialization signature

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-13-p6-implementation.md

Command to generate documentation for the 'rmcp' crate to find the real signature for 'initialize'. This is a mitigation step for potential signature mismatches.

```bash
cargo doc -p rmcp
```

--------------------------------

### Mempal Context Tool

Source: https://github.com/zhanghandong/mempal/blob/main/AGENTS.md

Assemble guided context packs using the mempal_context tool, following a specific hierarchy (dao_tian -> dao_ren -> shu -> qi). This aids in workflow, skill, or tool selection.

```bash
mempal_context
```

--------------------------------

### Run mempal CLI for development

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Execute the mempal CLI directly from the source code for development purposes. Use this to test commands without installation.

```bash
cargo run -p mempal-cli -- --help
```

```bash
cargo run -p mempal-cli --features rest -- serve --help
```

--------------------------------

### Mempal Command: Init

Source: https://github.com/zhanghandong/mempal/blob/main/README.md

Initialize mempal, inferring wing/rooms from project tree.

```bash
mempal init <DIR> [--dry-run]
```

--------------------------------

### Initialize Mempal Project

Source: https://github.com/zhanghandong/mempal/blob/main/README.md

Initialize mempal for a new project directory.

```bash
mempal init ~/code/myapp
```

--------------------------------

### Initialize and Index a Repository

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Initializes a local repository for mempal and ingests its content, associating it with a specific 'wing'. This is the first step in managing a project with mempal.

```bash
mempal init ~/code/myapp
mempal ingest ~/code/myapp --wing myapp
```

--------------------------------

### Manual CLI Commands for Testing

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-08-p0-implementation.md

Demonstrates the sequence of commands to manually test the init, ingest, and search pipeline of the mempal CLI.

```bash
cargo run -p mempal-cli -- init .

cargo run -p mempal-cli -- ingest . --wing mempal

cargo run -p mempal-cli -- search "workspace scaffold"
```

--------------------------------

### Mempal Command: KG Add

Source: https://github.com/zhanghandong/mempal/blob/main/README.md

Add a knowledge graph triple.

```bash
mempal kg add <S> <P> <O>
```

--------------------------------

### Verify P100 Guided Maintenance Run Spec

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-05-26-p100-guided-maintenance-run.md

Parses and lints the specification file for the P100 guided maintenance run.

```bash
agent-spec parse specs/p100-guided-maintenance-run.spec.md
```

```bash
agent-spec lint specs/p100-guided-maintenance-run.spec.md --min-score 0.7
```

--------------------------------

### Install Claude Code Hook

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-15-p8-implementation.md

Installs a shell script for the Claude Code hook. Ensures the script has execute permissions on Unix-like systems.

```rust
        std::fs::write(&claude_script, claude_content)?;
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let mut perms = std::fs::metadata(&claude_script)?.permissions();
            perms.set_mode(0o755);
            std::fs::set_permissions(&claude_script, perms)?;
        }
        println!("✓ installed Claude Code hook at {}", claude_script.display());
```

--------------------------------

### Example diary entry in JSON format

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

An example of how a diary entry can be structured in JSON format, including content, wing, room, and importance.

```json
{
  "content": "LESSON: always check repo docs before writing infrastructure code",
  "wing": "agent-diary",
  "room": "claude",
  "importance": 4
}
```

--------------------------------

### Verify Install Doctor Specifications

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-05-26-p98-release-install-doctor.md

Use agent-spec to parse and lint the install doctor specifications. Ensure the lint score meets the minimum requirement.

```bash
agent-spec parse specs/p98-release-install-doctor.spec.md
agent-spec lint specs/p98-release-install-doctor.spec.md --min-score 0.7
```

--------------------------------

### Search for P82 Instrumentation References

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-05-25-p82-opt-in-runtime-instrumentation-wrapper.md

Search for references to 'p82-opt-in-runtime-instrumentation-wrapper', 'P82 opt-in runtime instrumentation wrapper', or 'phase3 adoption wrap' across specified project files.

```bash
rg -n "p82-opt-in-runtime-instrumentation-wrapper|P82 opt-in runtime instrumentation wrapper|phase3 adoption wrap" AGENTS.md CLAUDE.md docs/MIND-MODEL-DESIGN.md src/core/protocol.rs
```

--------------------------------

### Dry-Run Reindex Output Example

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-23-p10-normalize-version-implementation.md

Example of the expected output for a dry-run reindex operation, indicating the number of drawers and sources that would be processed without making any changes.

```text
would reprocess 5 drawers from 2 sources
```

--------------------------------

### Run full lib and integration tests

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-13-p7-implementation.md

Execute all library and integration tests with specified features to confirm no regressions have been introduced. The P6 integration test 'cowork_peek' should remain unaffected.

```bash
cargo test --no-default-features --features model2vec --lib
cargo test --no-default-features --features model2vec --test cowork_peek
```

--------------------------------

### Run P100 Guided Maintenance Run Integration Tests

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-05-26-p100-guided-maintenance-run.md

Executes integration tests for the P100 guided maintenance run with JSON, plain, and invalid format outputs.

```bash
cargo test --test ops_runtime test_cli_maintenance_guided_run_json
```

```bash
cargo test --test ops_runtime test_cli_maintenance_guided_run_plain
```

```bash
cargo test --test ops_runtime test_cli_maintenance_guided_run_rejects_invalid_format
```

--------------------------------

### Check Release Readiness (Plain Text)

Source: https://github.com/zhanghandong/mempal/blob/main/docs/MIND-MODEL-DESIGN.md

Checks release readiness by verifying Cargo metadata, README, spec/plan inventory, runbooks, doctor availability, and schema support. Output is in plain text.

```bash
mempal release-readiness --format plain
```

--------------------------------

### Run Release Install Doctor (JSON)

Source: https://github.com/zhanghandong/mempal/blob/main/docs/MIND-MODEL-DESIGN.md

Performs a read-only operator diagnostic for release installs, outputting results in JSON. Useful for detecting mismatches between binary versions and database schemas.

```bash
mempal doctor --format json
```

--------------------------------

### Verify P62 Runtime Adoption CLI Guidance Specs

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-05-12-p62-runtime-adoption-cli-guidance.md

Parse and lint the specification file for the P62 runtime adoption CLI guidance.

```bash
agent-spec parse specs/p62-runtime-adoption-cli-guidance.spec.md
agent-spec lint specs/p62-runtime-adoption-cli-guidance.spec.md --min-score 0.7
```

--------------------------------

### Mempal Command: Ingest

Source: https://github.com/zhanghandong/mempal/blob/main/README.md

Chunk, embed, and store project data into mempal.

```bash
mempal ingest <DIR> --wing <W> [--dry-run]
```

--------------------------------

### Rust CLI Argument for Global Codex Hook Installation

Source: https://github.com/zhanghandong/mempal/blob/main/docs/specs/2026-04-14-p8-cowork-inbox-push.md

Defines a Rust CLI argument for the `mempal cowork-install-hooks` subcommand. The `global_codex` flag, when set to true, indicates that the Codex hook should be installed globally.

```rust
#[derive(Debug, Args)]
struct CoworkInstallHooks {
    /// Install hooks for this project's cwd only (default).
    /// Use --global to install the Codex hook in ~/.codex/hooks.json.
    #[arg(long, default_value_t = false)]
    global_codex: bool,
}
```

--------------------------------

### Mempal Phase 3 Runtime Adoption Tool

Source: https://github.com/zhanghandong/mempal/blob/main/AGENTS.md

Handle Phase-3 runtime adoption evidence with mempal_phase3, covering guidance, policy, record preparation, capture, evaluation, and analytics.

```bash
mempal_phase3
```

--------------------------------

### Run Verification Commands

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-24-p15-mcp-context-implementation.md

Execute these commands to verify the implementation. Includes parsing and linting specs, formatting checks, compilation, clippy checks, and running tests.

```bash
agent-spec parse specs/p15-mcp-context.spec.md
agent-spec lint specs/p15-mcp-context.spec.md --min-score 0.7
cargo fmt -- --check
cargo check
cargo clippy --workspace --all-targets -- -D warnings
cargo test
cargo check --features rest
```

--------------------------------

### Run Release Install Doctor (Plain Text)

Source: https://github.com/zhanghandong/mempal/blob/main/docs/MIND-MODEL-DESIGN.md

Performs a read-only operator diagnostic for release installs, outputting results in plain text. Checks binary version, schema version, and database path.

```bash
mempal doctor --format plain
```

--------------------------------

### Claude Code Hook Script Example

Source: https://github.com/zhanghandong/mempal/blob/main/docs/specs/2026-04-14-p8-cowork-inbox-push.md

This example shows how a Claude Code hook script might be set up. It calls `mempal cowork-drain` with specific targets and cwd parameters, utilizing environment variables for flexibility.

```bash
mempal cowork-drain --target claude --cwd "${CLAUDE_PROJECT_CWD:-$PWD}"
```

--------------------------------

### Check Release Readiness (JSON)

Source: https://github.com/zhanghandong/mempal/blob/main/docs/MIND-MODEL-DESIGN.md

Checks release readiness by verifying Cargo metadata, README, spec/plan inventory, runbooks, doctor availability, and schema support. Output is in JSON.

```bash
mempal release-readiness --format json
```

--------------------------------

### Get Taxonomy API

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Retrieves the taxonomy information from the mempal service.

```APIDOC
## GET /api/taxonomy

### Description
Retrieves the taxonomy information from the mempal service.

### Method
GET

### Endpoint
`/api/taxonomy`

### Response
#### Success Response (200)
(Response structure not specified in source)

### Request Example
```bash
curl 'http://127.0.0.1:3080/api/taxonomy'
```
```

--------------------------------

### Run Verification Commands

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-27-p37-knowledge-card-backfill-apply-implementation.md

Execute these commands to verify the implementation of the P37 Knowledge Card Backfill Apply. These commands cover parsing, linting, formatting checks, compilation, and testing.

```bash
agent-spec parse specs/p37-knowledge-card-backfill-apply.spec.md
agent-spec lint specs/p37-knowledge-card-backfill-apply.spec.md --min-score 0.7
cargo fmt --check
cargo check
cargo check --features rest
cargo clippy --workspace --all-targets -- -D warnings
cargo test
```

--------------------------------

### Get API Status

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Retrieves the current status of the mempal service.

```APIDOC
## GET /api/status

### Description
Retrieves the current status of the mempal service.

### Method
GET

### Endpoint
`/api/status`

### Response
#### Success Response (200)
(Response structure not specified in source)

### Request Example
```bash
curl 'http://127.0.0.1:3080/api/status'
```
```

--------------------------------

### MCP Server Request: Soft-Delete Drawer

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Example JSON request to soft-delete a specific drawer using its ID.

```json
{
  "drawer_id": "drawer_myapp_auth_1234abcd"
}
```

--------------------------------

### Update Cowork Session Status

Source: https://github.com/zhanghandong/mempal/blob/main/docs/MIND-MODEL-DESIGN.md

Use `cowork-session-status` to update the status of a specific team session, for example, pausing it.

```bash
mempal cowork-session-status --cwd "$PWD" --session-id p94-review --status paused
```

--------------------------------

### Run Fast Benchmark Sample

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Executes a benchmark test on a specified dataset, limiting the number of samples processed and directing the output to a JSONL file. Useful for quick performance evaluations.

```bash
mempal bench longmemeval /path/to/longmemeval_s_cleaned.json \
  --limit 20 \
  --out benchmarks/results_longmemeval_20.jsonl
```

--------------------------------

### CoworkInstallHooks Subcommand Definition

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-15-p8-implementation.md

Defines the 'cowork-install-hooks' subcommand with an optional 'global_codex' flag to control global Codex hook installation.

```rust
/// Install cowork hooks for Claude Code (project-level) and optionally Codex (global).
CoworkInstallHooks {
    #[arg(long)]
    global_codex: bool,
},
```

--------------------------------

### Create integration test file and helper harness

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-13-p7-implementation.md

Sets up the integration test file `tests/search_structured_signals.rs` with necessary imports and a harness function to create a hermetic database and embedder.

```rust
//! Integration tests for P7 mempal_search structured signals.
//!
//! Run with:
//!   cargo test --test search_structured_signals --no-default-features --features model2vec
//!
//! These tests build a hermetic tempfile palace.db, seed drawers, invoke
//! the real search pipeline (resolve_route + search_with_vector), and
//! construct SearchResultDto via the production code path
//! (SearchResultDto::with_signals_from_result). They do NOT touch
//! ~/.mempal/palace.db.

use mempal::aaak::analyze;
use mempal::core::db::Database;
use mempal::core::types::{Drawer, SourceType};
use mempal::core::utils::{build_drawer_id, current_timestamp};
use mempal::embed::{EmbedderFactory, Model2VecFactory};
use mempal::mcp::tools::SearchResultDto;
use mempal::search::{resolve_route, search_with_vector};
use std::path::PathBuf;
use tempfile::TempDir;

/// Bring up a tempfile palace.db, a real model2vec embedder, and optionally
/// seed the DB with the given drawers. Returns (TempDir guard, Database,
/// embedder factory).
///
/// Seeded drawers are inserted via the full ingest-style path so
/// `drawer_vectors` get populated — a search-only test needs real vectors.
async fn harness(seeds: &[(&str, &str, Option<&str>, &str)]) -> (TempDir, Database, Box<dyn EmbedderFactory>) {
    let tmp = TempDir::new().expect("tempdir");
    let db_path = tmp.path().join("palace.db");
    let db = Database::open(&db_path).expect("open db");

    let factory = Box::new(Model2VecFactory::default());
    let embedder = factory.build().await.expect("build embedder");

    // Seed drawers. Arguments per seed tuple: (wing, room_or_empty, source_file, content).
    for (wing, room, source_file, content) in seeds {
        let drawer_id = build_drawer_id(wing, *room, content);
        let vectors = embedder.embed(&[*content]).await.expect("embed");
        let vector = vectors.into_iter().next().expect("vector");
        let drawer = Drawer {
            drawer_id: drawer_id.clone(),
            wing: (*wing).to_string(),
            room: room.map(|r| r.to_string()),

```

--------------------------------

### Query Mempal REST API Taxonomy

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Example using curl to fetch the taxonomy endpoint of the mempal REST server.

```bash
curl 'http://127.0.0.1:3080/api/taxonomy'
```

--------------------------------

### Mempal Command: Taxonomy List/Edit

Source: https://github.com/zhanghandong/mempal/blob/main/README.md

Manage routing keywords for taxonomy.

```bash
mempal taxonomy list / edit
```

--------------------------------

### Mempal Knowledge Gate Tool

Source: https://github.com/zhanghandong/mempal/blob/main/CLAUDE.md

Performs a read-only promotion readiness check to evaluate if a knowledge drawer meets promotion criteria.

```bash
mempal_knowledge_gate
```

--------------------------------

### Query Mempal REST API Status

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Example using curl to fetch the status endpoint of the mempal REST server.

```bash
curl 'http://127.0.0.1:3080/api/status'
```

--------------------------------

### MCP Server Request: Edit Keywords

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Example JSON request to edit keywords associated with a specific wing and room.

```json
{
  "action": "edit",
  "wing": "myapp",
  "room": "auth",
  "keywords": ["auth", "login", "clerk"]
}
```

--------------------------------

### Stub main.rs for mempal-cli

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-08-p0-implementation.md

Provides a minimal main.rs file for the mempal-cli crate. This serves as a starting point for the command-line interface.

```rust
#![warn(clippy::all)]

fn main() {
    println!("mempal");
}
```

--------------------------------

### Codex CLI JSONL Format Example

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-11-p5-implementation.md

Describes the format of lines in a Codex CLI JSONL file, specifically identifying event messages.

```json
lines with {type: "event_msg", ...} — extract only these, skip synthetic context.
```

--------------------------------

### Mempal CLI Commands

Source: https://github.com/zhanghandong/mempal/blob/main/docs/specs/2026-04-08-mempal-design.md

Common Mempal CLI commands for initializing, ingesting data, searching, and managing the taxonomy. Includes options for different formats and specifying search parameters.

```bash
mempal init <dir>                          # 初始化 taxonomy
mempal ingest <dir>                        # 导入项目文件
mempal ingest <dir> --format convos        # 导入对话
mempal search "why clerk over auth0"       # 搜索（默认 raw 输出）
mempal search "auth decision" --wing myapp # 指定 wing
mempal wake-up                             # raw L0+L1
mempal wake-up --format aaak              # AAAK 压缩输出
mempal taxonomy list                       # 查看分类
mempal taxonomy edit <wing> <room>         # 编辑分类
mempal status                              # 宫殿概览
mempal serve                               # 启动 MCP + REST

```

--------------------------------

### Slack Export Format Example

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-11-p5-implementation.md

Illustrates the structure of a Slack export file, which is an array of message objects, each containing user, text, and a timestamp.

```json
export/<channel>/messages.json — array of {user, text, ts} objects.
```

--------------------------------

### Generate a compact AAAK-formatted refresh

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Specify the `--format aaak` option with the `wake-up` command to get a compact, AAAK-formatted memory summary.

```bash
mempal wake-up --format aaak
```

--------------------------------

### Preview Project Ingestion

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Use `--dry-run` with `mempal ingest` to preview the ingestion process, including file counts and skipped items, without writing any data.

```bash
mempal ingest ~/code/myapp --wing myapp --dry-run
```

--------------------------------

### Verify Implementation Requirements in Documentation

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-05-01-p52-phase-3-intake-roadmap.md

Searches the MIND-MODEL-DESIGN.md file for phrases detailing implementation requirements, including evidence, rollback criteria, and acceptance checks. Also checks for retrieval benefit requirements.

```bash
rg -n "must state evidence, rollback criteria, and acceptance checks before implementation begins|default-enabling card context or card embeddings requires measured retrieval benefit" docs/MIND-MODEL-DESIGN.md
```

--------------------------------

### Verification Commands for P20 Promotion Gate Policy

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-25-p20-promotion-gate-policy-implementation.md

A collection of commands to verify the implementation of the P20 promotion gate policy, including spec parsing, linting, code formatting checks, build checks, clippy analysis, and various test executions.

```bash
agent-spec parse specs/p20-promotion-gate-policy.spec.md
```

```bash
agent-spec lint specs/p20-promotion-gate-policy.spec.md --min-score 0.7
```

```bash
cargo fmt -- --check
```

```bash
cargo check
```

```bash
cargo clippy --workspace --all-targets -- -D warnings
```

```bash
cargo test --test knowledge_lifecycle -- --nocapture
```

```bash
cargo test
```

```bash
cargo check --features rest
```

--------------------------------

### Good Decision Record Example

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Captures context a future agent needs, including what was omitted, why, and next steps. This is crucial for effective knowledge transfer.

```text
Added CI with default + all-features matrix. Deliberately omitted rustfmt
because formatting drift exists in 2 test files — cleanup is a separate
commit. Follow-up: cargo fmt --all then add fmt check step. This completes
priority #1 from drawer_mempal_default_a295458d.
```

--------------------------------

### Query Mempal REST API Search

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Example using curl to perform a search query on the mempal REST API, specifying search parameters.

```bash
curl 'http://127.0.0.1:3080/api/search?q=clerk&wing=myapp'
```

--------------------------------

### Register mempal_peek_partner Tool

Source: https://github.com/zhanghandong/mempal/blob/main/docs/plans/2026-04-13-p6-implementation.md

Defines the `mempal_peek_partner` tool, including its description, parameters, and core logic for peeking into partner sessions.

```rust
@tool(
    name = "mempal_peek_partner",
    description = "Read the partner coding agent's live session log (Claude Code ↔ Codex) without storing it. Returns the most recent user+assistant messages from their current session file. Use this for CURRENT partner state; use mempal_search for CRYSTALLIZED past decisions. Peek is a pure read — never writes to mempal. Specify tool='auto' to let the server infer the partner from MCP ClientInfo."
)
async fn mempal_peek_partner(
    &self,
    Parameters(request): Parameters<PeekPartnerRequest>,
) -> std::result::Result<Json<PeekPartnerResponse>, ErrorData> {
    let tool = Tool::from_str_ci(&request.tool).ok_or_else(|| {
        ErrorData::invalid_params(
            format!("unknown tool `{}`: expected claude|codex|auto", request.tool),
            None,
        )
    })?;

    let caller_tool = self
        .client_name
        .lock()
        .ok()
        .and_then(|g| g.clone())
        .and_then(|n| Tool::from_str_ci(&n));

    let cwd = std::env::current_dir()
        .map_err(|e| ErrorData::internal_error(format!("cwd unavailable: {e}"), None))?;

    let cowork_req = CoworkPeekRequest {
        tool,
        limit: request.limit.unwrap_or(30),
        since: request.since,
        cwd,
        caller_tool,
        home_override: None,
    };

    let resp = peek_partner(cowork_req).map_err(|e| match e {
        PeekError::CannotInferPartner | PeekError::SelfPeek => {
            ErrorData::invalid_params(e.to_string(), None)
        }
        PeekError::Io(_) | PeekError::Parse(_) => {
            ErrorData::internal_error(e.to_string(), None)
        }
    })?;

    Ok(Json(PeekPartnerResponse {}));
```

--------------------------------

### Preview Ingest with Dry Run

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Simulates the initialization and ingestion process without making any actual changes to disk or consuming significant compute resources. Ideal for testing ingest configurations.

```bash
mempal init ~/code/monorepo --dry-run
mempal ingest ~/code/monorepo --wing monorepo --dry-run
```

--------------------------------

### MCP Server Request: Preview Ingest

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Example JSON request to preview an ingest operation without writing to storage. This returns the predicted 'drawer_id'.

```json
{
  "content": "decided to use Clerk for auth",
  "wing": "myapp",
  "dry_run": true
}
```

--------------------------------

### MCP Server Request: Ingest Memory

Source: https://github.com/zhanghandong/mempal/blob/main/docs/usage.md

Example JSON request for ingesting memory, specifying content, wing, room, source, and a dry_run option.

```json
{
  "content": "decided to use Clerk for auth",
  "wing": "myapp",
  "room": "auth",
  "source": "/repo/README.md",
  "dry_run": false
}
```