Metadata-Version: 2.4
Name: contmemo
Version: 0.6.0
Summary: Memory custodian agent for the Cont Hive ecosystem. Pruned from Cont (cont/core/memory_*) — same architecture, scope narrowed to memory only. SQLite-backed, offline, air-gapped.
Author: Sertan
Keywords: cont-hive,pdna,memory,sqlite,offline,air-gapped,scribe
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.0; extra == "embeddings"
Requires-Dist: numpy; extra == "embeddings"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# contmemo

<!-- v1 | 2026-05-05 | Sprint M8: Cont'tan budanmış (0.6.0) -->

> 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`](https://pypi.org/project/codent/) 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.

| Sprint | Scope                                         | Status  |
| ------ | --------------------------------------------- | ------- |
| M7     | Discovery — Cont memory inventory             | done    |
|        | Audit — memory ↔ knowledge boundary           | done    |
| M8     | Prune from Cont, publish 0.6.0                | done    |
| M9     | Cont shim (Cont imports `contmemo`)           | planned |
|        | JSONL → DB processor (Q5)                     | planned |

## Install

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

## Public API

```python
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

```bash
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:

```python
# 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:

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

## License

Private — internal Cont Hive component.
