The MentisDB Agent Memory Cookbook

2.1 Semantic Compression

Semantic compression turns many detailed thoughts into one high-signal summary without deleting the source records. In MentisDB, compression is explicit: append a Summary thought with ThoughtRole::Compression and references to the source window it summarizes.

The Pattern

• Select a bounded source window by concept, time, type, or agent.
• Write a compact summary that preserves decisions, blockers, and next actions.
• Use refs so auditors can expand the summary back to source thoughts.
• Retrieve compression thoughts before loading the full history.

use mentisdb::{
    BinaryStorageAdapter, MentisDb, ThoughtInput, ThoughtQuery,
    ThoughtRole, ThoughtType,
};

fn compress_project_window() -> io::Result<()> {
    let dir = tempfile::tempdir()?;
    let adapter = BinaryStorageAdapter::for_chain_key(
        dir.path(),
        "cookbook-compression",
    );
    let mut chain = MentisDb::open_with_storage(Box::new(adapter))?;

    chain.upsert_agent(
        "summarizer",
        Some("Summarizer"),
        Some("platform-team"),
        Some("Compresses detailed work logs into resumable summaries"),
        None,
    )?;

    let mut source_indices = Vec::new();
    for content in [
        "Found that webhook retries use exponential backoff.",
        "Decision: keep webhook delivery non-blocking for append latency.",
        "Constraint: failed webhooks must not fail thought appends.",
        "Open question: expose retry metrics in the CLI.",
    ] {
        let thought = chain.append_thought(
            "summarizer",
            ThoughtInput::new(ThoughtType::Finding, content)
                .with_concepts(["webhooks", "delivery"])
                .with_tags(["source-window"]),
        )?;
        source_indices.push(thought.index);
    }

    let summary = chain.append_thought(
        "summarizer",
        ThoughtInput::new(
            ThoughtType::Summary,
            "Webhook delivery is async and non-blocking. Retries use backoff; append failures must stay isolated from webhook failures. Remaining work: decide whether CLI retry metrics are needed.",
        )
        .with_role(ThoughtRole::Compression)
        .with_refs(source_indices)
        .with_concepts(["webhooks", "semantic-compression"])
        .with_tags(["summary", "compression"])
        .with_importance(0.85),
    )?.index;

    let compressed = chain.query(
        &ThoughtQuery::new()
            .with_roles(vec![ThoughtRole::Compression])
            .with_concepts_any(["webhooks"])
            .with_limit(1),
    );

    assert_eq!(compressed.len(), 1);
    assert_eq!(compressed[0].index, summary);
    assert_eq!(compressed[0].refs.len(), 4);
    Ok(())
}

Good Summaries

A good compression thought names the durable decisions, constraints, facts, and unresolved questions. It should not include every event. Its job is to make the next search or handoff cheaper and more accurate.