contmemo

Memory custodian for the Cont Hive ecosystem. Pruned from Cont — same architecture, scope narrowed to memory only.

contmemo is the memory layer of the Cont Hive, factored out of the cont agent runtime via upstream sync / downstream rebase discipline. Every COPY/ADAPT file in this package carries a source tracking comment (path + commit hash + sync date) so future Cont evolution can be rebased into Contmemo periodically — same pattern Linux distributions use to track upstream kernels.

Architecture mirrors Cont exactly. Memory is SQLite-backed (~/.cont/memory.sqlite), WAL + sync=NORMAL for atomicity, FTS5 BM25 for full-text recall, optional sentence-transformers for hybrid vector search. No file locks, no JSONL writers, no atomic-rename swaps — those were Brief v1 inventions that the v3 update (see docs/contmemo_brief_v3_update.md) retired in favour of SQLite WAL.

Scope is memory only. Recipe sanity, lifecycle, and evolution belong to a sibling package contrecipe. Pheromone / feedback / shutdown JSONL writers stay in Cont (Q2=A decision); Contmemo only reads them via trace_reader.

Status

Sprint M8 — Pruned rebirth (0.6.0).

The previous 0.0.1 → 0.5.0 line was written from scratch with a file-based discipline (fcntl + tmp+rename + fsync) that was incompatible with Cont's SQLite memory store. Those releases are dead; 0.6.0 starts fresh by pruning the relevant core/memory_* files out of the Cont repo.

Install

pip install contmemo                    # core, BM25-only
pip install contmemo[embeddings]        # + sentence-transformers (hybrid search)
pip install contmemo[dev]               # + pytest

Public API

from contmemo.core.memory_store import (
    memory_init_db, memory_remember, memory_recall, memory_hybrid_search,
    memory_forget, memory_get_context, memory_list_all, memory_semantic_stats,
)

memory_init_db()
mem_id = memory_remember(
    "RAG_main projesi /home/sertan/projects/RAG_main yolunda",
    memory_type="fact", source="user", importance=0.9,
)
hits = memory_hybrid_search("RAG_main nerede?", limit=5)

DB lives at ~/.cont/memory.sqlite (Cont's standard location — Contmemo shares the same store).

CLI

contmemo init               # initialize the DB and FTS5 triggers
contmemo stats              # print semantic memory statistics
contmemo recall "<query>"   # FTS5 / hybrid search

Design invariants (Brief v3 update)

These are the invariants the v3 update preserves from Brief v1, after dropping the file-based ones:

1. Single-writer. Contmemo is the only module that writes to memory.
2. Append-only event log. DELETE only at eviction time; INSERT-only otherwise.
3. Air-gapped. stdlib only on the hot path; embeddings extra is opt-in.
4. Memory-only scope. Recipes go to contrecipe.
5. LLM-free hot path. No model calls inside memory_remember/memory_recall.
6. No LLM-as-judge. Eviction and DLP filtering are deterministic; tests are human-curated.

Schema contracts (from docs/memory_knowledge_audit.md §5) preserved:

• importance REAL ∈ [0.0, 1.0]
• tags TEXT (JSON list)
• created_at TEXT (ISO 8601), NOT NULL
• content NOT NULL
• FTS5 triggers preserved exactly (otherwise BM25 recall breaks)

Source tracking

Every file pruned from Cont carries a header like:

# v1 | 2026-05-05 | Cont'tan budanmış (M8), scope: memory only
# Source: cont/core/memory_store.py
# Source commit: 1e2064f
# Last sync: 2026-05-05

Use this when rebasing upstream Cont changes:

git -C /home/sertan/projects/cont log <source_commit>..HEAD -- core/memory_store.py

License

Private — internal Cont Hive component.