co-memory

co-memory is a standalone Python package for building structured, time-aware memory from the wider agent workspace, not only from end-user chat history.

It is designed as an agent-native memory kernel for systems that need memory from:

• user sessions and run archives
• workspace files and artifacts
• todo and task lifecycle events
• agent outputs, decisions, and handoff material
• distilled system summaries

Release Status

• version: 0.2.0a1
• stage: alpha / preview
• package shape: standalone research kernel
• authority model: external host owns the authority store and runtime APIs
• stable public boundary: co_memory_ingest, co_memory_core, co_memory_bench
• experimental bench-side surface: command-style recall regression via co_memory_bench

Current release documents:

• Quickstart
• Public API
• Benchmarks
• Release Notes 0.2.0a1
• Release Readiness 0.2.0a1

What's New In 0.2.0a1

• packaged command-style recall regression through co_memory_bench
• added schema-constrained retrieval request helpers for glob, grep, source, category, subtype, after, before, and limit
• improved retrieval explainability with request/debug/item-level response serialization in the recall-command benchmark flow
• kept the stable deterministic ranking contract unchanged: rank_recall_candidates() remains the public ranking core
• kept retrieval-interface experimentation bench-side: command-style recall is included for host experimentation, but is not yet a stable public DSL

In practice, this means the release bundle now includes a clearer path for testing retrieval-interface optimizations before ranking, while keeping the stable public API narrow.

Why co-memory

Most memory systems start from chat logs and extend outward.

co-memory starts from the opposite assumption: useful memory for agent systems comes from the full workspace and execution environment. The package compiles that broader input surface into structured memory candidates with lineage, evidence, and time semantics, then runs deterministic routing, linking, segment building, and recall ranking on top of it.

What This Package Includes

• stable ingress contracts
• structured memory compilation
• deterministic routing and recall core
• fixture-based regression coverage
• LongMemEval benchmark tooling
• session-first standalone entrypoint for open-source users

What This Package Does Not Include

• raw log storage
• full host runtime orchestration
• authority DB hosting
• product-facing shared-memory APIs
• source-specific parsing and cleaning for every integration
• a stable public retrieval DSL

That boundary is intentional. co-memory freezes the structured memory layer and leaves most host-specific runtime, storage, and second-layer source processing to the host application.

Install

uv pip install .

Optional extras:

uv pip install ".[bench]"
uv pip install ".[llm]"
uv pip install ".[api]"
uv pip install ".[storage]"
uv pip install ".[cli]"
uv pip install ".[all]"

Verify The Release Bundle

List built-in fixtures:

co-memory-bench --list-fixtures

Run the current release smoke set:

co-memory-bench policy-routing-smoke.json
co-memory-bench event-compile-smoke.json
co-memory-bench session-compile-smoke.json
co-memory-bench recall-ranking-smoke.json
co-memory-bench recall-command-smoke.json

Run the documented LongMemEval smoke command:

uv run --python 3.12 -- co-memory-longmemeval co_memory_bench/fixtures/longmemeval-oracle-smoke.json --answer-mode extractive --judge-mode exact --retrieve-limit 4 --output-dir bench_results/longmemeval-smoke

Minimal Python Example

from co_memory_ingest import MemoryEvent, compile_memory_event

event = MemoryEvent.from_mapping(
    {
        "owner_scope": "user",
        "event_id": "evt-1",
        "event_type": "workspace.file_uploaded",
        "recorded_at": "2026-04-14T11:00:00Z",
        "title": "Uploaded roadmap",
        "summary_text": "Uploaded the final roadmap to the workspace.",
        "topic": "project roadmap",
        "source_kind": "workspace.file_uploaded",
        "source_origin_kind": "workspace",
        "canonical_file_id": "file-roadmap-1",
        "canonical_path": "workspace/project/roadmap.md",
        "tags": ["workspace", "roadmap"],
    }
)

compiled = compile_memory_event(event)
print(compiled.envelope.to_mapping())
print(compiled.plan)

For more examples, see Quickstart.

Stable Public Boundary

Treat these as the stable package boundary for standalone use:

• co_memory_ingest.__init__
• co_memory_ingest.contracts
• co_memory_core.__init__
• co_memory_core.memory_candidate
• co_memory_bench.__init__
• co_memory_bench.__main__
• co-memory-bench
• co-memory-longmemeval

Bench-specific note:

• co_memory_bench.longmemeval is importable, but its Python-level objects are not yet a frozen public API
• co_memory_core.recall_query and command-style recall helpers are included for benchmark regression and host experimentation, but remain experimental and bench-side

Benchmark Position

The main public benchmark harness is LongMemEval.

• preferred publication baseline: strict mode
• historical default mode should still be labeled label-assisted
• benchmark-only SQLite cache is not the product authority store

Current early public snapshot from strict-mode session-oriented runs:

• retrieval recall_any@1 = 0.79
• retrieval recall_any@5 = 0.98
• hot-cache retrieval, workers=1: P50 ~ 438 ms, P99 ~ 672 ms

Important caveat:

• LongMemEval is session-heavy and does not fully exercise the broader workspace-native memory model that co-memory is designed for

Documentation

• Release Materials Index
• Quickstart
• Integration Guide
• Public API
• Taxonomy
• Authority DB V1
• Benchmarks
• Release Checklist
• Release Notes 0.2.0a1
• Release Readiness 0.2.0a1

Acknowledgements

This project benefited from studying several memory systems and research implementations.

• gbrain: memory layering and operational memory framing
• HyperMem: hierarchical retrieval structure and coarse-to-fine memory organization
• ReMe: personal-memory style applicability thinking

These projects informed parts of the design direction. co-memory remains its own package boundary and architecture focused on agent-native structured memory from the wider workspace.