Metadata-Version: 2.4
Name: eml-memory
Version: 0.1.0
Summary: Typed, append-only memory store for agentic Claude / LLM sessions. Hybrid text + structured-tag query.
Author: Monogate Research
License: PROPRIETARY-PRE-RELEASE
Project-URL: Homepage, https://monogate.org
Project-URL: Repository, https://github.com/agent-maestro/eml-memory
Keywords: memory,agentic,llm,claude,vector-store,knowledge-graph
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: embeddings
Requires-Dist: numpy>=1.24; extra == "embeddings"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Dynamic: license-file

# eml-memory

Typed, append-only memory store for agentic Claude / LLM sessions.

This is the v0.1 carve-out of the structured agentic-memory system used
across the Monogate project ecosystem. It gives any LLM agent a typed,
append-only, queryable knowledge store that survives across sessions.

## Install

```bash
pip install eml-memory
```

## Quick start

```bash
$ eml-memory add fact "Buzzard drama: capacitor C7 spec mismatch" \
    --source notes/buzzard.md --confidence high
added m_a1b2c3d4ef (fact)

$ eml-memory query "Buzzard drama"
1 match

  [fact      ] [high  ] m_a1b2c3d4ef
    Buzzard drama: capacitor C7 spec mismatch
    source: notes/buzzard.md
```

Every entry has a typed schema:

| field        | meaning                                                |
|--------------|--------------------------------------------------------|
| `id`         | content + UTC timestamp hash                           |
| `type`       | `fact` / `decision` / `convention` / `todo` / `retraction` |
| `content`    | the main statement                                     |
| `source`     | optional citation                                      |
| `confidence` | `high` / `medium` / `low`                              |
| `tags`       | optional list of strings                               |
| `metadata`   | optional structured dict                               |

## Python API

```python
from eml_memory import MemoryStore

store = MemoryStore.default()                     # ~/.eml-memory/store.jsonl

# write
store.add("fact", "Lean theorems = 50",
          source="data/lean.md", confidence="high")

# read
for hit in store.query("Lean"):
    print(hit.id, hit.content)

# retract
store.retract("m_a1b2c3d4ef", "superseded by 2026-05-01 audit")
```

The store object is project-agnostic; pass `MemoryStore(path=...)` to
point at a per-repo or per-feature JSONL file.

## CLI

```text
eml-memory add TYPE CONTENT [--source X] [--confidence high|medium|low]
                            [--tag T ...] [--project P]
eml-memory query TEXT [--type T] [--project P] [--tag T] [--limit N]
                      [--include-retracted] [--verbose] [--json]
eml-memory list [--type T] ...
eml-memory retract ENTRY_ID REASON
eml-memory dashboard
eml-memory version
```

Override the store path via `$EML_MEMORY_STORE` or `--store PATH`.

## Storage format

Append-only JSONL — one entry per line. Retractions are first-class
entries pointing at the retracted ID; the original entry is never
overwritten. This means:

* You can `tail -f` the store from any process.
* Concurrent writers converge on the next read.
* Audit log is the source file itself.

## Roadmap

This is **v0.1** — text + tag query only. Planned:

* **v0.2** — caller-supplied embedding hooks for hybrid retrieval.
* **v0.3** — sync adapters (Linear / Notion / GitHub issues).
* **v1.0** — bundled embedding model + SQLite backend for high-volume
  use, plus the contradiction-scan / drift-check passes from the
  monogate-research curator.

## License

PROPRIETARY-PRE-RELEASE.
