# AbstractMemory

> Append-only, temporal, provenance-aware triple assertions with deterministic structured queries, SQLite/LanceDB persistence, and optional vector/semantic retrieval. Part of the AbstractFramework ecosystem.

Important notes for agents:
- Public API exports are defined in [src/abstractmemory/__init__.py](src/abstractmemory/__init__.py) (keep [docs/api.md](docs/api.md) aligned).
- `subject` / `predicate` / `object` are canonicalized (trim + lowercase) on write and query ([src/abstractmemory/models.py](src/abstractmemory/models.py), [tests/test_term_canonicalization.py](tests/test_term_canonicalization.py)).
- Vector search is opt-in: `query_text` requires a configured embedder (no keyword fallback) ([tests/test_in_memory_query_text_fallback.py](tests/test_in_memory_query_text_fallback.py)).
- `SQLiteTripleStore` is persistent and structured-query only; it rejects `query_text` and `query_vector` ([tests/test_sqlite_triple_store.py](tests/test_sqlite_triple_store.py)).
- Timestamps are compared/filtered as strings; use RFC-3339/UTC strings (see [docs/api.md](docs/api.md)).
- Release-channel note: this checkout is the source of truth for these docs; PyPI/tag state may drift from this source tree (see [README.md](README.md)).

Common commands:
```bash
python -m pytest -q
```

## Docs

- [README.md](README.md): overview + ecosystem
- [docs/getting-started.md](docs/getting-started.md): copy/paste usage (in-memory, SQLite, LanceDB, gateway embedder)
- [docs/api.md](docs/api.md): public API contracts
- [docs/stores.md](docs/stores.md): backend behavior + persistence details
- [docs/architecture.md](docs/architecture.md): boundaries + diagrams
- [docs/faq.md](docs/faq.md): common questions
- [docs/development.md](docs/development.md): local dev/test workflow
- [docs/README.md](docs/README.md): documentation index

## Code

- [src/abstractmemory/__init__.py](src/abstractmemory/__init__.py): public exports (source of truth)
- [src/abstractmemory/models.py](src/abstractmemory/models.py): `TripleAssertion` (+ `to_dict` / `from_dict`)
- [src/abstractmemory/store.py](src/abstractmemory/store.py): `TripleQuery`, `TripleStore` protocol
- [src/abstractmemory/in_memory_store.py](src/abstractmemory/in_memory_store.py): `InMemoryTripleStore`
- [src/abstractmemory/sqlite_store.py](src/abstractmemory/sqlite_store.py): `SQLiteTripleStore`
- [src/abstractmemory/lancedb_store.py](src/abstractmemory/lancedb_store.py): `LanceDBTripleStore`
- [src/abstractmemory/embeddings.py](src/abstractmemory/embeddings.py): `TextEmbedder`, `AbstractGatewayTextEmbedder`

## Tests

- [tests/test_term_canonicalization.py](tests/test_term_canonicalization.py): term + scope canonicalization contract
- [tests/test_triple_store_limits.py](tests/test_triple_store_limits.py): limit/order determinism contracts
- [tests/test_in_memory_query_text_fallback.py](tests/test_in_memory_query_text_fallback.py): `query_text` requires embedder (no fallback)
- [tests/test_sqlite_triple_store.py](tests/test_sqlite_triple_store.py): SQLite persistence + structured queries + semantic rejection
- [tests/test_lancedb_triple_store.py](tests/test_lancedb_triple_store.py): persistence + vector search + missing dependency hint
- [tests/conftest.py](tests/conftest.py): monorepo `sys.path` bootstrap

## Project

- [pyproject.toml](pyproject.toml): dependencies + optional extras
- [CHANGELOG.md](CHANGELOG.md): notable changes
- [CONTRIBUTING.md](CONTRIBUTING.md): dev workflow and expectations
- [SECURITY.md](SECURITY.md): responsible vulnerability reporting
- [LICENSE](LICENSE): license
- [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md): credits

## Optional

- [llms-full.txt](llms-full.txt): single-file agent context (includes core docs + key contracts)
