mempal

The P49 policy defines how external research-rs outputs are integrated into the mempal memory system. To prevent research from becoming a parallel authority to the dao, research outputs must follow a specific ingestion path that respects existing memory lifecycle gates.

Ingestion Rules

• Evidence Entry: Research raw or source output must enter the system as memory_kind=evidence with provenance=research.
• Knowledge Promotion: Research summaries or insights cannot directly create dao_tian, canonical, or promoted knowledge. They may only become candidate knowledge through the distill process from existing evidence references.
• Handling Contradictions: If research produces signals that contradict existing memory, these should be stored as evidence or counterexamples to be evaluated during later demotion or gate evaluation cycles.

Constraints

• Research is considered external qi and is not a dao container.
• Research must not bypass lifecycle gates or directly create promoted knowledge types.

The mempal-ingest crate provides two primary methods for breaking down content into manageable chunks for embedding:

1. Fixed Window Chunking: chunk_text(text, window, overlap) splits a continuous string into chunks of a specific size (window) with a specified amount of overlap between adjacent chunks. This is useful for standard text files.
2. Conversation/QA Chunking: chunk_conversation(transcript) is designed for dialogue-style data (like chat logs). It splits content based on conversational turns (e.g., separating user/assistant pairs) to preserve the context of individual exchanges.

// Example of fixed window chunking
let text = "a".repeat(2000);
let chunks = chunk_text(&text, 800, 100);

// Example of conversation chunking
let transcript = "> How do I fix this?\nTry restarting.\n\n> What about the config?\nCheck settings.toml.";
let chunks = chunk_conversation(transcript);

Mempal uses project_identity(cwd) to determine the target inbox.

• Git Repositories: The identity is normalized to the git repository root. This means any sub-directory within the same git repo will resolve to the same project_identity, allowing seamless collaboration across different folders in the same project.
• Non-Git Projects: The identity falls back to the raw current working directory (cwd). In these cases, sub-directories are isolated from each other.
• Special Characters: The encode_project_identity function replaces / with - but preserves other special characters (like spaces or brackets) that the OS filesystem can handle.
• Codex Integration: For Codex users, mempal cowork-drain --cwd-source stdin-json is used to read the cwd field from the Codex hook's stdin JSON. This ensures the correct project identity is used regardless of the shell's $PWD.

In the mempal Cowork protocol, every message push generates a unique, trackable receipt_handle (also referred to as message_id).

Key characteristics of these handles:

• Format: They are prefixed with msg_ followed by a 12-hex string.
• Determinism: When using build_message_id, the ID is deterministic based on pushed_at, from, and content.
• Uniqueness: Even with identical content and timestamps, concurrent pushes are guaranteed to receive unique handles.
• Fallback Mechanism: If the system cannot read the existing receipts log (e.g., due to malformed lines or IO issues), it uses a collision-resistant fallback handle instead of the deterministic one to ensure the push still succeeds.
• MCP Compatibility: When using the mempal-mcp-server, the mempal_cowork_push tool returns a message_id that is required by the CoworkPushResponse schema.

// Example of the expected message_id format
// "msg_" + 12-hex handle
// e.g., "msg_a1b2c3d4e5f6"

In the Mempal system, Evaluators serve an advisory role and are strictly prohibited from acting as lifecycle writers. This ensures that the system maintains deterministic replay, evidence citation, and audit semantics.

What Evaluators CAN do:

• Recommend promotion or demotion candidates.
• Propose supporting, verification, teaching, and counterexample evidence references.
• Produce contradiction candidates and risk notes.
• Explain why a knowledge item appears ready or unsafe.

What Evaluators MUST NOT do:

• Directly mutate the status of a knowledge item.
• Append lifecycle refs as authoritative gate input.
• Bypass deterministic promotion or demotion gates.
• Satisfy reviewer requirements via evaluator-only review.
• Create automatic promotion or demotion paths.

Note: Canonicalization of dao_tian requires a human reviewer; evaluator-only canonization is forbidden.

The card-context rollback policy is designed to manage the adoption of card-aware context. It monitors runtime_adoption_events for specific signals to determine if a feature should be disabled.

How it works

1. Evidence Collection: The system looks for events where track=card_context, feature=include_cards, and signal=rollback.
2. Evaluation: The rollback executor checks if these signals exist in the runtime adoption history.
3. Action: If rollback is required and --execute is used, the executor sets context.include_cards_default=false in the local configuration.

Constraints

• Rollback execution cannot alter knowledge card lifecycle states (promotion/demotion).
• Rollback execution cannot write or mutate runtime adoption events.
• If include_cards_default is already false, the execution is a no-op and will report applied=false even if rollback is required.