tessera

TESSERA (Temporal Evolving State Synthesis with Explicit Relations and Atomic Memories) is a text-first memory and evidence layer for AI agents. It is published as tessera-agent-memory, while the Python import and CLI remain tessera, requires Python 3.9+, and is licensed under MIT. The current version is 0.0.1. The project frames itself as memory infrastructure rather than the final reasoning agent. Markdown and textual sources stay authoritative; indexes, graphs, caches and evidence records are derived and rebuildable. Retrieval returns structured evidence rather than a generated answer, and the README states that relevance is not treated as truth, confidence or authority, that sources are not silently rewritten during indexing, and that a generative LLM is not required for the basic retrieval path. Interfaces and usage - CLI: tessera init, write, index, query, plus config show/list/doctor/unregister. Non-interactive init requires an explicit --sources policy, and material changes to an existing config must first be inspected with --dry-run and then allowed with --update-existing. - Python API: TesseraEngine(storage_dir=...).build_index() and retrieve_context(query, top_n=...), returning fields such as id, score with score_explain, relevant_evidence, full memory body, source path, stable source-document identity, source version hashes, evidence span and related memory IDs. - MCP: an optional tessera[mcp] extra adds the MCP transport (SDK v1.30+, Python 3.10+, certified on 3.12), with tessera-mcp --project /absolute/project; an optional tessera[llm] extra adds an HTTP LLM bridge. Memory model and storage - Exactly three semantic drawers are preserved: facts, preferences and insights. - Identity is separated from file location and content version, so moving a document does not automatically create a new memory or source identity. - Configuration is human-readable schema v2: store.path is the generated-memory destination, sources.roots is an explicit read/index allow list, and index.path is disposable derived state inside the project. A user-global registry can remember named stores without copying or merging their memory. - Storage resolution order is explicit path, TESSERA_STORAGE_DIR, deprecated LAO_MEM_DIR, nearest project config, then a named global entry; CLI operations fail with an actionable error if none is selected. - Markdown is the only canonical writable format; unsupported formats and arbitrary JSON ingestion are rejected before any storage, registry, graph, index or Evidence Ledger mutation. - Writes follow a deterministic contract: path validation, detection, optional transformation, admission, persistence. Safe content is accepted unchanged; empty input and direct known hostile instructions are rejected; quoted examples and suspicious-tag-only input go to review without persistence side effects. - An optional .tessera-ignore supports a documented subset of ignore syntax (comments, *, ?, **, directory suffix, ordered ! re-inclusion); mandatory exclusions such as .git, the derived index and credential artifacts cannot be re-included. Evaluation and status A compact, non-sensitive ledger versions a deterministic LongMemEval V1 dev-50 retrieval profile, recording aggregate retrieval metrics, frozen inputs, configuration, commit provenance, cost and hashes without committing the dataset or ground-truth mappings. Every pull request declares benchmark applicability; offline reporting checks run per PR and the frozen 50-query profile is gated against the PR base SHA. The README notes these scores measure evidence retrieval, not final-answer correctness. TESSERA is described as an evolving Foundation. Available today include canonical metadata and document classification, stable memory and source identity, explainable local retrieval, query-aware relevant evidence, the Evidence Ledger and provenance, relation parsing/navigation, Python/CLI/MCP surfaces, and deterministic CI with sanity evaluation. Items still being tested include incremental and idempotent indexing, broader text ingestion and segmentation, a LongMemEval baseline, query-aware graph expansion, temporal state, arbitration of conflicting evidence, and adaptive retrieval. Documentation covers architecture, concepts, query examples, the retrieval output contract, a roadmap, research references and a change policy; the repository is currently maintained by Luigi Ferronatto.