# AbstractMemory

> Durable, append-only agent memory for Python: temporal, provenance-aware triple assertions with deterministic queries and optional vector retrieval (layer 1), plus a MemorySystem facade that composes them with an append-only journal into a usage-weighted memory graph — reconstruction, attention, identity, valence, diary, consolidation, and a replay stream (layer 2). Part of the AbstractFramework ecosystem.

Key facts for agents:

- The authoritative export list is [src/abstractmemory/__init__.py](src/abstractmemory/__init__.py); [docs/api.md](docs/api.md) documents every export with verified signatures.
- Reads are pure: `reconstruct`, inspection, replay, and `entity_card` deposit nothing; `commit_selection` is the only strengthening path.
- Append-only, no deletion: updates are new assertions; belief revision is closure records; forgetting is decay + closures + silencing.
- The journal's monotonic `seq` is the time axis: anchor reads with `as_of`/`at_seq`/`since_seq` for deterministic replay.
- All three stores are vector-capable when constructed with an embedder; `query_text` without one raises (no keyword fallback).
- Terms are canonicalized (trim + lowercase); timestamps compare as RFC-3339/UTC strings.

## Core Docs

- [README.md](README.md): project overview, install, quick examples for both layers
- [docs/getting-started.md](docs/getting-started.md): setup, first triples, first MemorySystem session
- [docs/architecture.md](docs/architecture.md): the two-layer model, journal-as-time-axis, the reconstruction union, presence ≠ use, append-only posture
- [docs/api.md](docs/api.md): full API reference, grouped by surface
- [docs/faq.md](docs/faq.md): common questions and current limits
- [docs/troubleshooting.md](docs/troubleshooting.md): symptom-oriented fixes — setup, retrieval, embedding spaces, durability, maintenance

## Topic Deep Dives

- [docs/memory-system.md](docs/memory-system.md): the cognitive model — emergent working memory, two access counts, valence/gradation, identity cores, diary, sleep/consolidation, observability
- [docs/stores.md](docs/stores.md): backend behavior and persistence details (in-memory, SQLite, LanceDB)
- [docs/operator.md](docs/operator.md): read-only inspection and verification of an entity's memory home

## Contributing

- [docs/development.md](docs/development.md): local setup and test workflow
- [CONTRIBUTING.md](CONTRIBUTING.md): contributor workflow, and how to cite the three design-record series
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md): participation standards and reporting
- [SECURITY.md](SECURITY.md): vulnerability reporting

## Optional

- [CHANGELOG.md](CHANGELOG.md): release history
- [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md): credits and lineage
- [docs/README.md](docs/README.md): documentation index
- [llms-full.txt](llms-full.txt): the full documentation corpus in one file
