AbstractMemory 0.0.1__tar.gz → 0.0.2__tar.gz

abstractmemory-0.0.2/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.DS_Store
+.venv/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/

abstractmemory-0.0.2/ACKNOWLEDGMENTS.md

@@ -0,0 +1,15 @@
+# Acknowledgments
+
+AbstractMemory builds on a number of great open-source tools and ideas.
+
+## Libraries
+
+- **LanceDB** (`lancedb`) — optional persistent/vector backend used by `LanceDBTripleStore` (see `.[lancedb]` extra in `pyproject.toml`).
+- **pytest** (`pytest`) — development and contract tests (see `.[dev]` extra in `pyproject.toml`).
+- **Hatchling** (`hatchling`) — packaging/build backend (see `[build-system]` in `pyproject.toml`).
+
+## Ecosystem
+
+- The broader **AbstractFramework** project for shaping the boundaries between runtime provenance, model execution, and memory storage.
+
+If we missed a credit, please open a small PR to update this file.

abstractmemory-0.0.2/ACKNOWLEDMENTS.md

@@ -0,0 +1,3 @@
+# Acknowledgments (moved)
+
+This file is a compatibility alias. See [`ACKNOWLEDGMENTS.md`](ACKNOWLEDGMENTS.md).

abstractmemory-0.0.2/CHANGELOD.md

@@ -0,0 +1,3 @@
+# Changelog (moved)
+
+This file is a compatibility alias. See [`CHANGELOG.md`](CHANGELOG.md).

abstractmemory-0.0.2/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) (pre-1.0).
+
+## Unreleased
+
+## 0.0.2 - 2026-02-04
+
+### Added
+- User-facing documentation set with getting started, API, stores, architecture diagram, and FAQ.
+- Agent-oriented context files: `llms.txt` and `llms-full.txt`.
+
+### Changed
+- `LanceDBTripleStore` non-semantic queries now apply `order` by `observed_at` before applying `limit` (deterministic behavior aligned with `InMemoryTripleStore`).
+
+### Fixed
+- Ordering/limit interaction for non-semantic queries in `LanceDBTripleStore` (covered by new tests).
+
+## 0.0.1 - 2026-01-12
+
+### Added
+- `TripleAssertion` and `TripleQuery` data models.
+- `InMemoryTripleStore` (dependency-free) and `LanceDBTripleStore` (optional).
+- `AbstractGatewayTextEmbedder` adapter for gateway-managed embeddings.

abstractmemory-0.0.2/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+Thanks for your interest in improving AbstractMemory.
+
+This repository uses a `src/` layout and keeps the public API intentionally small.
+
+## Development setup
+
+Requirements:
+- Python 3.10+ (see `pyproject.toml`)
+
+Install (editable):
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Optional (LanceDB backend + tests):
+
+```bash
+python -m pip install -e ".[lancedb]"
+```
+
+More details: [`docs/development.md`](docs/development.md).
+
+## Run tests
+
+```bash
+python -m pytest -q
+```
+
+## What to contribute
+
+Good first contributions:
+- Improve docs (keep statements evidence-based and link to code/tests).
+- Add tests for edge cases and contracts.
+- Make error messages more actionable.
+- Add small, well-scoped features that keep the v0 API minimal.
+
+## Contribution guidelines
+
+- Keep changes focused; avoid drive-by refactors.
+- Add tests for behavior changes (especially store/query semantics).
+- Update docs when you change public behavior:
+  - `README.md` and `docs/getting-started.md` for user-facing usage
+  - `docs/api.md` for public API contracts
+  - `CHANGELOG.md` for notable changes
+- If you add a new dependency, keep it optional unless strictly required.
+
+## Security issues
+
+Please do not open public issues for vulnerabilities. See [`SECURITY.md`](SECURITY.md).

{abstractmemory-0.0.1 → abstractmemory-0.0.2}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 AbstractMemory Team
+Copyright (c) 2024 Laurent-Philippe Albou
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

abstractmemory-0.0.2/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: AbstractMemory
+Version: 0.0.2
+Summary: AbstractMemory: temporal, provenance-aware semantic memory primitives for AbstractFramework.
+Project-URL: AbstractFramework (monorepo), https://github.com/lpalbou/abstractframework
+Author: Laurent-Philippe Albou
+License: MIT
+License-File: LICENSE
+Keywords: agents,knowledge-graph,memory,temporal,triples
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: lancedb; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: lancedb
+Requires-Dist: lancedb; extra == 'lancedb'
+Description-Content-Type: text/markdown
+
+# AbstractMemory (early / WIP)
+
+AbstractMemory is a small Python library for **append-only, temporal, provenance-aware triple assertions** with a **deterministic query API** and optional **vector/semantic retrieval**.
+
+## Status
+- This package is still early: API and storage details may change.
+- Implemented today: `TripleAssertion`, `TripleQuery`, `InMemoryTripleStore`, `LanceDBTripleStore`, `AbstractGatewayTextEmbedder`.
+  - Source of truth for exports: [`src/abstractmemory/__init__.py`](src/abstractmemory/__init__.py)
+- Requires Python 3.10+ (see [`pyproject.toml`](pyproject.toml))
+
+## Install
+
+From PyPI (when published):
+
+```bash
+python -m pip install AbstractMemory
+```
+
+Optional persistent backend + vector search:
+
+```bash
+python -m pip install "AbstractMemory[lancedb]"
+```
+
+Note: the distribution name is `AbstractMemory` (pip is case-insensitive). The import name is `abstractmemory`.
+
+From source (recommended for this monorepo package):
+
+```bash
+python -m pip install -e .
+```
+
+Optional persistent backend + vector search:
+
+```bash
+python -m pip install -e ".[lancedb]"
+```
+
+## Quick example
+
+```python
+from abstractmemory import InMemoryTripleStore, TripleAssertion, TripleQuery
+
+store = InMemoryTripleStore()
+store.add(
+    [
+        TripleAssertion(
+            subject="Scrooge",
+            predicate="related_to",
+            object="Christmas",
+            scope="session",
+            owner_id="sess-1",
+            provenance={"span_id": "span_123"},
+        )
+    ]
+)
+
+hits = store.query(TripleQuery(subject="scrooge", scope="session", owner_id="sess-1"))
+assert hits[0].object == "christmas"  # terms are canonicalized (trim + lowercase)
+```
+
+## Documentation
+
+- Getting started: [`docs/getting-started.md`](docs/getting-started.md)
+- FAQ: [`docs/faq.md`](docs/faq.md)
+- Architecture (with diagrams): [`docs/architecture.md`](docs/architecture.md)
+- Stores/backends: [`docs/stores.md`](docs/stores.md)
+- API reference: [`docs/api.md`](docs/api.md)
+- Development: [`docs/development.md`](docs/development.md)
+
+## Project
+
+- Changelog: [`CHANGELOG.md`](CHANGELOG.md)
+- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Security: [`SECURITY.md`](SECURITY.md)
+- License: [`LICENSE`](LICENSE)
+- Acknowledgments: [`ACKNOWLEDGMENTS.md`](ACKNOWLEDGMENTS.md)
+
+## Design principles (v0)
+
+- **Triples-first** representation with temporal fields (`observed_at`, `valid_from`, `valid_until`).
+  - Implemented in `TripleAssertion`: [`src/abstractmemory/models.py`](src/abstractmemory/models.py)
+- **Append-only**: represent updates by adding a new assertion with fresh provenance.
+  - Implemented by both stores: [`src/abstractmemory/in_memory_store.py`](src/abstractmemory/in_memory_store.py), [`src/abstractmemory/lancedb_store.py`](src/abstractmemory/lancedb_store.py)
+- **No direct AbstractCore dependency**: embeddings can be obtained via an AbstractGateway HTTP API.
+  - Implemented by `AbstractGatewayTextEmbedder`: [`src/abstractmemory/embeddings.py`](src/abstractmemory/embeddings.py)

abstractmemory-0.0.2/README.md

@@ -0,0 +1,86 @@
+# AbstractMemory (early / WIP)
+
+AbstractMemory is a small Python library for **append-only, temporal, provenance-aware triple assertions** with a **deterministic query API** and optional **vector/semantic retrieval**.
+
+## Status
+- This package is still early: API and storage details may change.
+- Implemented today: `TripleAssertion`, `TripleQuery`, `InMemoryTripleStore`, `LanceDBTripleStore`, `AbstractGatewayTextEmbedder`.
+  - Source of truth for exports: [`src/abstractmemory/__init__.py`](src/abstractmemory/__init__.py)
+- Requires Python 3.10+ (see [`pyproject.toml`](pyproject.toml))
+
+## Install
+
+From PyPI (when published):
+
+```bash
+python -m pip install AbstractMemory
+```
+
+Optional persistent backend + vector search:
+
+```bash
+python -m pip install "AbstractMemory[lancedb]"
+```
+
+Note: the distribution name is `AbstractMemory` (pip is case-insensitive). The import name is `abstractmemory`.
+
+From source (recommended for this monorepo package):
+
+```bash
+python -m pip install -e .
+```
+
+Optional persistent backend + vector search:
+
+```bash
+python -m pip install -e ".[lancedb]"
+```
+
+## Quick example
+
+```python
+from abstractmemory import InMemoryTripleStore, TripleAssertion, TripleQuery
+
+store = InMemoryTripleStore()
+store.add(
+    [
+        TripleAssertion(
+            subject="Scrooge",
+            predicate="related_to",
+            object="Christmas",
+            scope="session",
+            owner_id="sess-1",
+            provenance={"span_id": "span_123"},
+        )
+    ]
+)
+
+hits = store.query(TripleQuery(subject="scrooge", scope="session", owner_id="sess-1"))
+assert hits[0].object == "christmas"  # terms are canonicalized (trim + lowercase)
+```
+
+## Documentation
+
+- Getting started: [`docs/getting-started.md`](docs/getting-started.md)
+- FAQ: [`docs/faq.md`](docs/faq.md)
+- Architecture (with diagrams): [`docs/architecture.md`](docs/architecture.md)
+- Stores/backends: [`docs/stores.md`](docs/stores.md)
+- API reference: [`docs/api.md`](docs/api.md)
+- Development: [`docs/development.md`](docs/development.md)
+
+## Project
+
+- Changelog: [`CHANGELOG.md`](CHANGELOG.md)
+- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Security: [`SECURITY.md`](SECURITY.md)
+- License: [`LICENSE`](LICENSE)
+- Acknowledgments: [`ACKNOWLEDGMENTS.md`](ACKNOWLEDGMENTS.md)
+
+## Design principles (v0)
+
+- **Triples-first** representation with temporal fields (`observed_at`, `valid_from`, `valid_until`).
+  - Implemented in `TripleAssertion`: [`src/abstractmemory/models.py`](src/abstractmemory/models.py)
+- **Append-only**: represent updates by adding a new assertion with fresh provenance.
+  - Implemented by both stores: [`src/abstractmemory/in_memory_store.py`](src/abstractmemory/in_memory_store.py), [`src/abstractmemory/lancedb_store.py`](src/abstractmemory/lancedb_store.py)
+- **No direct AbstractCore dependency**: embeddings can be obtained via an AbstractGateway HTTP API.
+  - Implemented by `AbstractGatewayTextEmbedder`: [`src/abstractmemory/embeddings.py`](src/abstractmemory/embeddings.py)

abstractmemory-0.0.2/SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+If you discover a security vulnerability, please report it responsibly so we can address it before public disclosure.
+
+## Reporting a vulnerability
+
+Please **do not** open a public GitHub issue for security reports.
+
+Preferred reporting method (private):
+- Use GitHub’s **“Report a vulnerability”** / **Security Advisory** workflow on the AbstractFramework monorepo:
+  - `https://github.com/lpalbou/abstractframework`
+
+If private reporting is not available on the repository:
+- Contact the maintainers privately via the repository’s contact channels (e.g. GitHub profile contact).
+
+## What to include
+
+To help us triage quickly, include:
+- A clear description of the issue and potential impact
+- The affected component(s) and file paths (if known)
+- Steps to reproduce (or a minimal proof-of-concept)
+- The version(s) impacted (see `pyproject.toml`) and your environment details
+- Any suggested mitigation or patch (optional)
+
+## Disclosure timeline
+
+We will do our best to acknowledge receipt promptly and work with you on a coordinated disclosure timeline.
+
+Thank you for helping keep users safe.

abstractmemory-0.0.2/docs/README.md

@@ -0,0 +1,19 @@
+# AbstractMemory Documentation
+
+AbstractMemory is a small, dependency-light Python library that provides **append-only, temporal, provenance-aware triple assertions** plus a **deterministic query API**, with optional **vector/semantic retrieval**.
+
+## Start here
+- Getting started: [`getting-started.md`](getting-started.md)
+- FAQ: [`faq.md`](faq.md)
+- Architecture: [`architecture.md`](architecture.md)
+- Stores/backends: [`stores.md`](stores.md)
+- API reference: [`api.md`](api.md)
+- Development: [`development.md`](development.md)
+
+## Related
+- Package overview: [`README.md`](../README.md)
+- Changelog: [`CHANGELOG.md`](../CHANGELOG.md)
+- Contributing: [`CONTRIBUTING.md`](../CONTRIBUTING.md)
+- Security: [`SECURITY.md`](../SECURITY.md)
+- License: [`LICENSE`](../LICENSE)
+- Acknowledgments: [`ACKNOWLEDGMENTS.md`](../ACKNOWLEDGMENTS.md)

abstractmemory-0.0.2/docs/api.md

@@ -0,0 +1,95 @@
+# API Reference (v0)
+
+> This package is early/WIP. The API is intentionally small and may change.
+
+## Public exports
+
+All public exports are defined in [`src/abstractmemory/__init__.py`](../src/abstractmemory/__init__.py):
+- Data model: `TripleAssertion`
+- Query model: `TripleQuery`
+- Store interface: `TripleStore` (typing protocol)
+- Stores: `InMemoryTripleStore`, `LanceDBTripleStore`
+- Embeddings: `TextEmbedder` (protocol), `AbstractGatewayTextEmbedder`
+
+## `TripleAssertion`
+
+Source: [`src/abstractmemory/models.py`](../src/abstractmemory/models.py)
+
+An **append-only semantic assertion** with temporal + provenance metadata.
+
+Fields (selected):
+- `subject`, `predicate`, `object` (strings)
+- `scope`: `"run" | "session" | "global"` (string)
+- `owner_id`: identifier within the scope (e.g. a session id)
+- `observed_at`: ISO-8601/RFC-3339 timestamp string (default: current UTC to seconds)
+- `valid_from`, `valid_until`: optional validity window (see `TripleQuery.active_at`)
+- `provenance`: free-form dict (e.g. `{"span_id": "...", "artifact_id": "..."}`)
+- `attributes`: free-form dict (extractor evidence/context, retrieval metadata, etc.)
+
+Behavior:
+- `TripleAssertion` is immutable (`@dataclass(frozen=True)`).
+- Terms are **canonicalized on creation** (trim + lowercase). This is part of the matching contract. Evidence: `TripleAssertion.__post_init__` in [`src/abstractmemory/models.py`](../src/abstractmemory/models.py) and [`tests/test_term_canonicalization.py`](../tests/test_term_canonicalization.py).
+  - Canonicalization discards original casing/whitespace. Preserve raw strings separately (e.g. in `attributes`) if needed.
+- Serialization helpers: `to_dict()` / `from_dict(...)` (same file).
+
+## `TripleQuery`
+
+Source: [`src/abstractmemory/store.py`](../src/abstractmemory/store.py)
+
+Used by `TripleStore.query(...)`.
+
+Core filters:
+- `subject`, `predicate`, `object` (exact match after canonicalization)
+- `scope`, `owner_id`
+- `since`, `until`: compare `observed_at` timestamps
+- `active_at`: filters by validity window intersection:
+  - include if `(valid_from is None or valid_from <= active_at)` and `(valid_until is None or valid_until > active_at)`
+  - end is **exclusive** (`valid_until > active_at`), consistent across stores
+
+Semantic/vector filters (optional):
+- `query_text`: text to embed for vector search (requires a configured `embedder`)
+- `query_vector`: bypass embedding generation (vector provided by caller)
+- `vector_column`: column name to use (default `"vector"`)
+- `min_score`: cosine similarity threshold
+
+Result shaping:
+- `limit`: `<= 0` means “unbounded” (see tests in [`tests/test_triple_store_limits.py`](../tests/test_triple_store_limits.py))
+- `order`: `"asc" | "desc"` (by `observed_at` for non-semantic queries)
+
+Vector query results:
+- When using `query_text` or `query_vector`, stores attach retrieval metadata to `TripleAssertion.attributes["_retrieval"]`.
+  - In-memory: `{ "score": <cosine>, "metric": "cosine" }`
+  - LanceDB: `{ "score": <cosine>, "distance": <_distance>, "metric": "cosine" }`
+
+## `TripleStore` (protocol)
+
+Source: [`src/abstractmemory/store.py`](../src/abstractmemory/store.py)
+
+Minimal store interface:
+- `add(assertions: Iterable[TripleAssertion]) -> list[str]` (returns generated assertion ids)
+- `query(q: TripleQuery) -> list[TripleAssertion]`
+- `close() -> None`
+
+## Stores
+
+Implementation sources:
+- In-memory: [`src/abstractmemory/in_memory_store.py`](../src/abstractmemory/in_memory_store.py)
+- LanceDB: [`src/abstractmemory/lancedb_store.py`](../src/abstractmemory/lancedb_store.py)
+
+See [`docs/stores.md`](stores.md) for behavior differences and persistence details.
+
+## Embeddings
+
+Source: [`src/abstractmemory/embeddings.py`](../src/abstractmemory/embeddings.py)
+
+`TextEmbedder` protocol:
+- `embed_texts(texts: Sequence[str]) -> list[list[float]]`
+
+`AbstractGatewayTextEmbedder`:
+- Calls an AbstractGateway embeddings endpoint via HTTP (`POST` JSON `{ "input": [...] }`)
+- Expects an OpenAI-like response shape with a `data` list containing `embedding` (and optionally `index`)
+
+Tip: keep a stable provider/model per store instance to preserve a consistent embedding space (the store itself does not enforce this).
+
+See also:
+- Common questions and implementation notes: [`docs/faq.md`](faq.md)

abstractmemory-0.0.2/docs/architecture.md

@@ -0,0 +1,138 @@
+# AbstractMemory — Architecture (v0 / early)
+
+> Updated: 2026-02-04
+
+This document describes **what exists in this repository today** and the boundaries it enforces.
+
+## Scope
+
+What this package *is*:
+- A small library for **append-only, temporal, provenance-aware triple assertions**.
+- A **deterministic query API** over those assertions, with optional vector/semantic retrieval.
+
+What this package is *not* (by design, not implemented here):
+- A text extractor/summarizer (no AbstractCore dependency).
+- A runtime provenance system (spans/artifacts live elsewhere; this package only stores pointers in `provenance`).
+- A full knowledge-graph reasoner (no inference, joins, ontologies in v0).
+
+Evidence (module map):
+- Data model: [`src/abstractmemory/models.py`](../src/abstractmemory/models.py)
+- Query model + protocol: [`src/abstractmemory/store.py`](../src/abstractmemory/store.py)
+- Stores: [`src/abstractmemory/in_memory_store.py`](../src/abstractmemory/in_memory_store.py), [`src/abstractmemory/lancedb_store.py`](../src/abstractmemory/lancedb_store.py)
+- Embeddings adapter: [`src/abstractmemory/embeddings.py`](../src/abstractmemory/embeddings.py)
+
+## Component diagram
+
+```mermaid
+flowchart LR
+  APP[Your app / extractor] --> TA[TripleAssertion\nmodels.py]
+  APP --> TQ[TripleQuery\nstore.py]
+
+  subgraph AbstractMemory
+    TA --> IM[InMemoryTripleStore\nin_memory_store.py]
+    TA --> LDB[LanceDBTripleStore\nlancedb_store.py]
+    TQ --> IM
+    TQ --> LDB
+
+    TE[TextEmbedder\nembeddings.py] --> IM
+    TE --> LDB
+    AG[AbstractGatewayTextEmbedder\nembeddings.py] --> TE
+  end
+
+  LDB <--> DISK[(LanceDB tables\non disk)]
+  AG <--> GW[AbstractGateway\nEmbeddings API]
+
+  IM --> APP
+  LDB --> APP
+```
+
+## Core representation
+
+The primitive is an **append-only triple assertion**:
+
+```
+subject  --predicate-->  object
+```
+
+Represented by `abstractmemory.models.TripleAssertion` (see [`src/abstractmemory/models.py`](../src/abstractmemory/models.py)):
+- Canonical fields: `subject`, `predicate`, `object` (trimmed + lowercased on creation)
+- Partitioning fields: `scope` (`run|session|global`) + optional `owner_id`
+- Time: `observed_at` (when recorded), optional `valid_from`/`valid_until` (when considered true)
+- Provenance: `provenance` dict (e.g. `span_id`, `artifact_id`)
+- Extra payload: `attributes` dict (evidence/context + retrieval metadata)
+
+Evidence:
+- Canonicalization behavior is tested in [`tests/test_term_canonicalization.py`](../tests/test_term_canonicalization.py).
+
+## Storage backends (v0)
+
+See also: [`docs/stores.md`](stores.md)
+
+### In-memory (default)
+
+`abstractmemory.in_memory_store.InMemoryTripleStore` is dependency-free and stores rows in process memory.
+
+Key behavior:
+- Optional vector indexing when constructed with an `embedder`.
+- `query_text` requires an embedder; there is **no keyword fallback** (raises `ValueError`).
+
+Evidence:
+- Store implementation: [`src/abstractmemory/in_memory_store.py`](../src/abstractmemory/in_memory_store.py)
+- Contract test: [`tests/test_in_memory_query_text_fallback.py`](../tests/test_in_memory_query_text_fallback.py)
+
+### LanceDB (optional, persistent)
+
+`abstractmemory.lancedb_store.LanceDBTripleStore` stores assertions in a local-path LanceDB table.
+
+Key behavior:
+- Creates the table on first `add(...)` (schema inferred from inserted rows).
+- Stores `provenance`/`attributes` as JSON strings plus a canonical `text` column.
+- Optional vector column when an `embedder` is configured.
+
+Evidence:
+- Store implementation: [`src/abstractmemory/lancedb_store.py`](../src/abstractmemory/lancedb_store.py)
+- Persistence test (reopen and query): [`tests/test_lancedb_triple_store.py`](../tests/test_lancedb_triple_store.py)
+
+## Query semantics (deterministic)
+
+See also: [`docs/api.md`](api.md)
+
+`abstractmemory.store.TripleQuery` supports:
+- Exact matching on canonicalized `subject`/`predicate`/`object`
+- Partitioning via `scope` + `owner_id`
+- Time filters: `since` / `until` over `observed_at`
+- Validity window filtering: `active_at`
+  - include if `(valid_from is None or valid_from <= active_at)` and `(valid_until is None or valid_until > active_at)`
+  - `valid_until` is **exclusive** (shared across both stores)
+- Semantic queries:
+  - `query_text` → embed then vector search (requires embedder)
+  - `query_vector` → caller-supplied vector
+  - `min_score` → cosine similarity threshold (implemented by both stores)
+
+Important implementation detail (timestamps are strings):
+- Both stores compare/filter timestamps as strings.
+- Use ISO-8601/RFC-3339 in UTC (e.g. `2026-01-01T00:00:00+00:00`) to keep ordering predictable.
+
+Evidence:
+- Limit semantics (`limit <= 0` means unbounded): [`tests/test_triple_store_limits.py`](../tests/test_triple_store_limits.py)
+
+## Embeddings boundary (no AbstractCore dependency)
+
+AbstractMemory defines a minimal `TextEmbedder` protocol and ships an HTTP adapter:
+- `abstractmemory.embeddings.TextEmbedder`: interface used by stores
+- `abstractmemory.embeddings.AbstractGatewayTextEmbedder`: calls an AbstractGateway embeddings endpoint
+
+Evidence:
+- Adapter implementation: [`src/abstractmemory/embeddings.py`](../src/abstractmemory/embeddings.py)
+
+## Roadmap (non-binding)
+
+Likely next steps (not implemented in this package as of 2026-02-04):
+- More backends (e.g. SQLite reference store) while keeping the same `TripleStore` protocol
+- Higher-level ingestion helpers (still likely owned by gateway/runtime, not this package)
+- Schema evolution and compaction strategies for long-lived stores
+
+Next:
+- Getting started: [`docs/getting-started.md`](getting-started.md)
+- API reference: [`docs/api.md`](api.md)
+- FAQ: [`docs/faq.md`](faq.md)

abstractmemory-0.0.2/docs/development.md

@@ -0,0 +1,31 @@
+# Development
+
+## Local setup
+
+Editable install:
+
+```bash
+python -m pip install -e .
+```
+
+Dev extras (tests):
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Optional LanceDB tests/backends:
+
+```bash
+python -m pip install -e ".[lancedb]"
+```
+
+## Run tests
+
+```bash
+python -m pytest -q
+```
+
+Notes:
+- LanceDB-dependent tests are skipped when `lancedb` is not installed. See [`tests/test_lancedb_triple_store.py`](../tests/test_lancedb_triple_store.py).
+- The test suite bootstraps `sys.path` for monorepo layouts (see [`tests/conftest.py`](../tests/conftest.py)).