tulving 0.0.1__tar.gz

tulving-0.0.1/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"f5b5d2a0-03e6-446c-903b-19003d524a39","pid":65688,"procStart":"639186885348535720","acquiredAt":1783117493637}

tulving-0.0.1/CLAUDE.md

@@ -0,0 +1,136 @@
+# CLAUDE.md — Tulving Project Instructions
+
+> Project instructions for Claude Code. Scope: **v0.1.0 only** (ADR-016).
+
+---
+
+## Current State — READ FIRST
+
+**Pre-development.** No source code exists yet. **Do not start coding until the owner gives the green light.**
+
+Document authority order (when they disagree, higher wins):
+1. `docs/project-management/revision-plan.md` — audit corrections, decisions D1–D12
+2. `docs/architecture/architecture.md` + `docs/adrs/adr-015`, `adr-016`
+3. `docs/specs/*.md` — module specs (predate the audit; apply D1–D12 when implementing)
+4. `docs/legacy_docs/` — **superseded; never implement from these**
+
+Reader-friendly scope tour: `docs/v0.1-overview.md`.
+
+**Pending owner decisions (do not act without instruction):**
+- Green light to begin coding.
+
+**Naming (resolved 2026-07-03, ADR-017):** the project is **Tulving** — named after Endel Tulving, the psychologist who established that memory has types (episodic vs semantic), mirroring this SDK's typed-memory model. Formerly "Engram" (dropped: collision with the funded engram.org). PyPI name `tulving` verified available — register early. The future Kairos integration package will be `kairos-ai-tulving`.
+
+---
+
+## Project Overview
+
+A model-agnostic Python SDK giving a single AI agent persistent, structured, searchable working memory, with **token-budget context curation (`curate(query, token_budget)`) as the headline primitive**. Also runs as a local MCP server for Claude Code. Zero infrastructure: one SQLite file; vectors optional.
+
+**v0.1.0 ships:** core engine (store/get/search, typed memories, key-supersede) · curation + orient mode · lazy decay & eviction · per-agent sessions with summarization · MCP server (6 tools) · embedding/LLM adapters + JSON export.
+**Deferred (one line):** knowledge graph, all multi-agent machinery, semantic contradiction detection, extra formats/backends — see ADR-016.
+
+## Kairos (sibling project)
+
+Reference implementation for patterns, security stance, and testing methodology: `C:\Users\abrah\OneDrive\Documents\Projects\ClaudeCode\Kairos\kairos` · https://github.com/govanxa/kairos
+
+- PyPI package is **`kairos-ai`** (never `kairos-sdk`); core is zero-dependency — match that discipline.
+- Plugins ship as separate packages in a `plugins/` monorepo; **`kairos-ai-evidence`** (0.2.0) is the worked example and the packaging model for the future Tulving↔Kairos integration.
+- Integration facts for later: `Workflow(hooks=[...])` with `ExecutorHooks` subclasses (there is no `plugins=` kwarg for hooks; `ctx.memory` injection is impossible); `kairos-ai-evidence` verdicts (verified/conflicting/insufficient) are the candidate backend for v0.2 contradiction detection.
+
+---
+
+## Non-Negotiable Design Decisions (from the audit — full detail in revision-plan.md)
+
+1. **Upsert (D1):** `store()` on an existing key supersedes — archive old (`SUPERSEDED`), back-link, insert new. Never raise on duplicate key.
+2. **Lazy decay (D2):** importance computed on read: `base_importance * 0.5^(hours_since_last_access / half_life[type])`. No startup decay pass. `evict()` exempts `pinned` and `DECISION`.
+3. **Data model (D3):** `last_accessed_at` (updated on get/search-hit/curate-inclusion), `archive_reason` enum, partial unique index `UNIQUE(key) WHERE archived=0`, `memory_tags` junction table, `meta` table `{schema_version, embedding_model_id, dimension, distance_metric}`, `source_entry_ids` on summaries.
+4. **Concurrency (ADR-015):** one process/many threads; advisory lock file refuses a second writer; SQLite embedding BLOBs are source of truth, `.hnsw` is a rebuildable cache; DB write first, reconcile at `startup()`; warn on OneDrive/network paths.
+5. **hnswlib realities:** int-label↔UUID mapping; `mark_deleted` + rebuild-on-threshold compaction; `max_elements` resize policy; `space='cosine'`, `score = 1 - distance`; exclusive lock on index writes; over-fetch to survive post-filtering.
+6. **Exceptions (D6):** `TulvingError` → `MemoryStoreError`, `StorageError`, `SecurityError`, `ConfigError`, `VectorIndexError`, `ScopeError`. **Never** define `MemoryError` or `IndexError` (builtin shadows).
+7. **Identity (D7):** `agent_id` bound at `Memory(...)` construction.
+8. **Cheap `__init__` (D8):** lifecycle work lives in explicit `startup()` — time-boxed, non-fatal, single-runner. Constructors never call LLMs or full-table scan.
+9. **Per-agent sessions:** active-session checks and abandonment detection scoped by `agent_id`, per-session `last_activity_at`.
+10. **MCP server:** thin wrapper; tools = `store`, `get`, `search`, `curate`, `forget`, `list_keys` (orient = `curate(mode="orient")`); async handlers offload to a thread pool; `llm=None` degrades loudly, never silently; SIGTERM flush is best-effort — startup recovery is primary.
+
+---
+
+## Quick Reference
+
+```bash
+pip install -e ".[dev]"
+pytest
+pytest --cov=tulving --cov-report=term-missing
+mypy tulving/                     # strict
+ruff check tulving/ tests/ && ruff format tulving/ tests/
+tulving-mcp --memory-path ./test_memory
+```
+
+## Project Structure (v0.1.0)
+
+```
+tulving/
+├── CLAUDE.md                    ← you are here
+├── pyproject.toml
+├── docs/                        ← see docs/README.md for the map
+├── tulving/
+│   ├── __init__.py              ← public API exports
+│   ├── enums.py                 ← MemoryType, MatchType, ArchiveReason, SessionStatus
+│   ├── exceptions.py            ← TulvingError hierarchy (decision 6)
+│   ├── security.py              ← redact (keys + content), leaf-name sanitize, path containment
+│   ├── memory.py                ← Memory (primary API) + startup()
+│   ├── entry.py                 ← MemoryEntry, SourceInfo, Relationship
+│   ├── store.py                 ← MemoryStore (CRUD engine)
+│   ├── kv_index.py              ← exact match + prefix scan (no namespaces)
+│   ├── semantic_index.py        ← label mapping, mark_deleted, compaction
+│   ├── context/
+│   │   ├── curator.py           ← ContextCurator (token-budget curation, orient mode)
+│   │   ├── summarizer.py        ← call-budgeted, source back-links
+│   │   ├── decay.py             ← lazy decay + reason-aware eviction
+│   │   └── lifecycle.py         ← per-agent sessions, gap detection
+│   ├── adapters/
+│   │   ├── embeddings.py        ← protocol + LocalEmbedder (extra) + OpenAIEmbedder
+│   │   ├── llm.py               ← protocol + one adapter, call budget
+│   │   └── storage.py           ← protocol + SQLiteBackend + InMemoryBackend
+│   ├── mcp/server.py            ← 6 MCP tools, thread-pool offload
+│   └── export/formats.py        ← JSON round-trip (re-embed on import, ID remap)
+├── tests/                       ← mirrors source
+└── examples/
+```
+
+## Build Order (TDD)
+
+1. `enums.py`, `exceptions.py`
+2. `tests/test_security.py` → `security.py`
+3. `tests/test_entry.py` → `entry.py`
+4. `adapters/storage.py` (SQLite WAL + InMemory; D3 schema; `PRAGMA user_version` migrations)
+5. `tests/test_store.py` → `store.py`
+6. `tests/test_kv_index.py` → `kv_index.py`
+7. `adapters/embeddings.py`
+8. `tests/test_semantic_index.py` → `semantic_index.py`
+9. `tests/test_memory.py` → `memory.py` (integration; `startup()`; lock file)
+10. `tests/test_curator.py` → `context/curator.py`
+11. `tests/test_decay.py` → `context/decay.py`
+12. `tests/test_summarizer.py` → `context/summarizer.py`
+13. `tests/test_lifecycle.py` → `context/lifecycle.py`
+14. `tests/test_mcp_server.py` → `mcp/server.py`
+15. `tests/test_export.py` → `export/formats.py`
+
+**Mandatory regression tests from the audit:** decay idempotency across repeated startups · supersede against an archived row holding the same key · search excludes archived vectors · curate with oversize/tiny/empty budgets · startup never abandons another agent's session · adapter swap (any model change) forces rebuild · batch-created entries are searchable · purge refuses summarization sources unless explicit · DECISION/pinned survive evict at importance ~0 · second process on same path is refused.
+
+## Coding Standards
+
+- Python 3.11+; `str | None`; `@dataclass` for data, `Protocol` for interfaces
+- `ruff format` / `ruff check`; `mypy` strict; line length 100; Google docstrings
+- pytest, TDD; 90%+ coverage on core; InMemoryBackend in tests; mock all LLM/embedding calls
+- **Dependencies:** core = stdlib + `hnswlib`. Extras: `[local]` (sentence-transformers/torch — never core), `[mcp]`, `[openai]`, `[postgres]`, `[kairos]` → `kairos-ai`. Token counting: `tiktoken` if available, `len/4` fallback with safety margin — never block on it.
+
+## Security Requirements
+
+1. Redaction covers key names **and** content (token-shape regexes, word-boundary patterns) in exports, MCP responses, curated context.
+2. `[a-zA-Z0-9_-]` whitelist for leaf names only; directories via realpath containment (Windows-aware).
+3. Credentials from environment only; adapters reject inline API keys.
+4. `ScopeError` ≠ `SecurityError` (decision 6).
+5. MCP server local-only; no network binding.
+6. No encryption at rest in v0.1 — documented warning; don't store secrets.
+7. 100% coverage on security functions.

tulving-0.0.1/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: tulving
+Version: 0.0.1
+Summary: The context-budget engine for AI agents — persistent typed memory with token-budget curation. Name-holding pre-release; v0.1 in active development.
+Project-URL: Author, https://github.com/govanxa
+Author-email: Abraham <abraham@fscoder.dev>
+Keywords: agents,ai,context,curation,llm,mcp,memory
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Tulving
+
+> *The context-budget engine for AI agents.*
+
+**Status: pre-release (0.0.1) — name-holding release; v0.1 is in active development.**
+
+Tulving is a model-agnostic Python SDK that gives an AI agent persistent, structured, searchable working memory — and, as its headline capability, curates that memory back into a fixed token budget:
+
+```python
+ctx = memory.curate("resuming work on the auth refactor", token_budget=4000)
+```
+
+Named after **Endel Tulving**, the psychologist who established that memory has types (episodic vs semantic). Typed memories — facts, decisions, observations, plans, summaries, each with its own lifecycle — are Tulving's core data model.
+
+## What v0.1 will ship
+
+- **Core memory engine** — store / get / semantic search over typed memories; zero infrastructure (one SQLite file, local vectors optional, no API key required)
+- **Token-budget context curation** — `curate(query, token_budget)` selects, ranks, and trims memories into a prompt-ready block; `orient` mode for cold starts
+- **Lazy decay & eviction** — importance fades per-type over time; decisions never decay; nothing is destroyed, only archived
+- **Sessions** — per-agent session tracking, end-of-session summarization, abandoned-session recovery
+- **MCP server** — six tools for Claude Code and other MCP clients, with single-writer safety
+- **Adapters & export** — pluggable embeddings/LLM, JSON round-trip export
+
+By the same author: [Kairos](https://github.com/govanxa/kairos) (`kairos-ai`) — contract-enforced AI workflows. A `kairos-ai-tulving` integration plugin is planned.
+
+## License
+
+TBD (MIT or Apache 2.0) — will be finalized with the v0.1 release.

tulving-0.0.1/README.md

@@ -0,0 +1,28 @@
+# Tulving
+
+> *The context-budget engine for AI agents.*
+
+**Status: pre-release (0.0.1) — name-holding release; v0.1 is in active development.**
+
+Tulving is a model-agnostic Python SDK that gives an AI agent persistent, structured, searchable working memory — and, as its headline capability, curates that memory back into a fixed token budget:
+
+```python
+ctx = memory.curate("resuming work on the auth refactor", token_budget=4000)
+```
+
+Named after **Endel Tulving**, the psychologist who established that memory has types (episodic vs semantic). Typed memories — facts, decisions, observations, plans, summaries, each with its own lifecycle — are Tulving's core data model.
+
+## What v0.1 will ship
+
+- **Core memory engine** — store / get / semantic search over typed memories; zero infrastructure (one SQLite file, local vectors optional, no API key required)
+- **Token-budget context curation** — `curate(query, token_budget)` selects, ranks, and trims memories into a prompt-ready block; `orient` mode for cold starts
+- **Lazy decay & eviction** — importance fades per-type over time; decisions never decay; nothing is destroyed, only archived
+- **Sessions** — per-agent session tracking, end-of-session summarization, abandoned-session recovery
+- **MCP server** — six tools for Claude Code and other MCP clients, with single-writer safety
+- **Adapters & export** — pluggable embeddings/LLM, JSON round-trip export
+
+By the same author: [Kairos](https://github.com/govanxa/kairos) (`kairos-ai`) — contract-enforced AI workflows. A `kairos-ai-tulving` integration plugin is planned.
+
+## License
+
+TBD (MIT or Apache 2.0) — will be finalized with the v0.1 release.

tulving-0.0.1/docs/README.md

@@ -0,0 +1,30 @@
+# Tulving Documentation
+
+> **Scope:** v0.1.0 — single-agent, local-first memory SDK with token-budget context curation, plus an MCP server for Claude Code.
+
+## Start here
+
+1. **[v0.1-overview.md](v0.1-overview.md)** — plain-language tour of the six capability areas. Read this first.
+2. **[architecture/architecture.md](architecture/architecture.md)** — the canonical v0.1.0 architecture: API surface, storage model, concurrency, security, future roadmap.
+3. **[specs/](specs/)** — per-module specifications (subject to the corrections in the revision plan).
+
+## Folder map
+
+| Folder | Contents |
+|---|---|
+| [architecture/](architecture/) | v0.1.0 architecture + [database strategy](architecture/database-strategy.md) |
+| [adrs/](adrs/) | Architecture Decision Records 001–016 ([index](adrs/README.md)) |
+| [specs/](specs/) | Module specs in play for v0.1.0 (Phase 1 core, Phase 3 context, Phase 5 adapters/MCP) |
+| [project-management/](project-management/) | [Revision plan](project-management/revision-plan.md) (audit corrections D1–D12, authoritative over specs) · [Market research](project-management/market-research.md) |
+| [legacy_docs/](legacy_docs/) | ⚠️ **Superseded — do not implement from these.** Old architecture, deferred Phase 2/4 specs, and Kairos integration docs written against APIs that don't exist. Reference material for future redesigns only. |
+
+## Authority order (when documents disagree)
+
+1. `project-management/revision-plan.md` (decisions D1–D12)
+2. `architecture/architecture.md` + ADR-015/016
+3. Module specs in `specs/`
+4. Anything in `legacy_docs/` — historical only
+
+## Naming
+
+- **Tulving** (final, 2026-07-03) — after Endel Tulving, who established that memory has types; see [ADR-017](adrs/adr-017-project-name.md). Formerly "Engram" (dropped: collision with the unrelated, funded engram.org).

tulving-0.0.1/docs/adrs/README.md

@@ -0,0 +1,28 @@
+# Architecture Decision Records (ADRs)
+
+> **Project:** Tulving
+> **Convention:** ADRs are numbered sequentially. Once accepted, they are immutable; superseding decisions get a new ADR.
+
+---
+
+## Index
+
+| ADR | Title | Status | Notes |
+|---|---|---|---|
+| [001](adr-001-python-first.md) | Python as primary language | Accepted | |
+| [002](adr-002-sdk-plus-mcp.md) | SDK library + MCP server distribution | Accepted | |
+| [003](adr-003-sqlite-default.md) | SQLite + hnswlib as default backends | Accepted | Concurrency boundaries defined in ADR-015 |
+| [004](adr-004-local-embeddings-default.md) | Local embeddings by default | Accepted | Revised: `[local]` extra (torch never in core); "no network" softened to "after first-run model fetch" — see revision plan D9 |
+| [005](adr-005-four-retrieval-modes.md) | Four retrieval modes | Partially deferred | Graph retrieval deferred with Phase 2 (ADR-016); v0.1 = key, semantic, temporal |
+| [006](adr-006-decisions-never-decay.md) | Decision memories never auto-decay or auto-evict | Accepted | |
+| [007](adr-007-json-serializable-content.md) | String content, JSON-serializable metadata | Accepted | |
+| [008](adr-008-agent-id-trust-model.md) | Agent identity trusted from orchestrator | Accepted | Reframed: cooperative isolation, not authZ — scope violations raise `ScopeError`, not `SecurityError` |
+| [009](adr-009-summarization-archives-not-deletes.md) | Summarization archives originals, never destroys | Accepted | Enforced via `source_entry_ids` back-links (revision plan D3) |
+| [010](adr-010-security-first.md) | Security as a first-class concern | Accepted | Revised per revision plan D10: content scanning, word-boundary patterns, path containment, no-encryption position |
+| [011](adr-011-kairos-as-sibling-not-dependency.md) | Kairos is a sibling, not a dependency | Accepted | Dependency name is `kairos-ai` (not `kairos-sdk`); integration deferred, will follow the `kairos-ai-evidence` plugin packaging pattern |
+| [012](adr-012-mcp-tool-design.md) | MCP tools designed for agent ergonomics | Accepted | Tool set trimmed to six in v0.1 (see ADR-016) |
+| [013](adr-013-session-detection.md) | Three-layer session detection with graceful degradation | Accepted | Sessions are per-agent; startup recovery is the primary mechanism |
+| [014](adr-014-contradiction-detection.md) | Contradiction detection flags, not blocks | Partially deferred | v0.1 keeps only deterministic key-collision supersede; semantic detection deferred (similarity ≠ contradiction) — candidate backend: `kairos-ai-evidence` |
+| [015](adr-015-concurrency-model.md) | Single-writer concurrency model for Tier-1 | Accepted | **New** — one process/many threads; advisory lock file; index as rebuildable cache |
+| [016](adr-016-v01-scope.md) | v0.1.0 scope: single-agent core, curation-first | Accepted | **New** — the in/out table; defers Phase 2, Phase 4, semantic contradiction |
+| [017](adr-017-project-name.md) | Project name: Tulving | Accepted | **New** — replaces working title "Engram"; future Kairos plugin: `kairos-ai-tulving` |

tulving-0.0.1/docs/adrs/adr-001-python-first.md

@@ -0,0 +1,16 @@
+# ADR-001: Python as Primary Language
+
+**Status:** Accepted
+**Date:** 2026-05-04
+**Modules affected:** All
+
+## Context
+Tulving must ship in the language its target users work in. The AI agent ecosystem is overwhelmingly Python.
+
+## Decision
+**Python first. Same rationale as Kairos ADR-001.** TypeScript port considered for future phases.
+
+## Consequences
+- Immediate adoption by the agent developer community.
+- Consistent with Kairos — both SDKs in the same language simplifies integration.
+- Modern Python (3.11+) with type hints, `@dataclass`, `Protocol`.

tulving-0.0.1/docs/adrs/adr-002-sdk-plus-mcp.md

@@ -0,0 +1,20 @@
+# ADR-002: SDK Library + MCP Server Distribution
+
+**Status:** Accepted
+**Date:** 2026-05-04
+**Modules affected:** All, 5.6
+
+## Context
+Tulving needs to be usable both as a Python library imported into code AND as a standalone server that Claude Code or other MCP clients can connect to.
+
+## Decision
+**Tulving ships as both: `pip install tulving` for SDK use, `pip install tulving[mcp]` for MCP server.**
+
+- The SDK is the primary distribution. Developers import it directly.
+- The MCP server wraps the SDK and exposes it as tools via the Model Context Protocol.
+- Both use the same underlying `Memory` class. The MCP server is a thin transport layer.
+
+## Consequences
+- Claude Code users get Tulving without writing Python — just configure the MCP server.
+- Python developers get a clean import API without MCP overhead.
+- The MCP dependency (`mcp` package) is optional — core SDK has no dependency on it.

tulving-0.0.1/docs/adrs/adr-003-sqlite-default.md

@@ -0,0 +1,21 @@
+# ADR-003: SQLite + hnswlib as Default Backends
+
+**Status:** Accepted
+**Date:** 2026-05-04
+**Modules affected:** 1.1, 1.3, 5.4
+
+## Context
+Tulving needs persistence and vector search. The default must require zero infrastructure — no separate database server, no cloud service, no Docker.
+
+## Decision
+**SQLite for structured storage, hnswlib for vector indexing. Both are file-based, zero-config, and embedded.**
+
+- SQLite in WAL mode for concurrent read support.
+- hnswlib for approximate nearest neighbor search (HNSW algorithm).
+- Both persist to the same directory: `./tulving_memory/tulving.db` and `./tulving_memory/tulving.hnsw`.
+- Production backends (Postgres, Redis, Pinecone, Qdrant) available via Phase 5 adapters.
+
+## Consequences
+- `pip install tulving` → works immediately. No infrastructure setup.
+- Performance is sufficient for single-agent and small multi-agent workloads (thousands to low millions of entries).
+- Large-scale production deployments switch backends without code changes.

tulving-0.0.1/docs/adrs/adr-004-local-embeddings-default.md

@@ -0,0 +1,20 @@
+# ADR-004: Local Embeddings by Default, No API Key Required
+
+**Status:** Accepted
+**Date:** 2026-05-04
+**Modules affected:** 1.3, 5.2
+
+## Context
+Semantic search requires embedding vectors. Cloud embedding APIs (OpenAI, Cohere) are higher quality but require API keys and network access. Local models are lower quality but zero-friction.
+
+## Decision
+**Default: local `sentence-transformers/all-MiniLM-L6-v2` (384 dims). No API key required.**
+
+- `pip install tulving` includes the local embedder. Semantic search works immediately.
+- Cloud embedders available as optional extras: `pip install tulving[openai]`.
+- Switching embedders requires re-embedding existing memories (handled by `rebuild()` command).
+
+## Consequences
+- Zero-friction first experience. No account, no API key, no network.
+- Lower embedding quality than cloud models — acceptable for working memory use cases.
+- The `sentence-transformers` dependency adds ~500MB for the model. Documented in install notes.

tulving-0.0.1/docs/adrs/adr-005-four-retrieval-modes.md

@@ -0,0 +1,23 @@
+# ADR-005: Four Retrieval Modes, Not One
+
+**Status:** Accepted
+**Date:** 2026-05-04
+**Modules affected:** 1.2, 1.3, 2.3, 3.1
+
+## Context
+Most memory systems default to one retrieval mode — usually vector search. But agents ask different kinds of questions that demand different access patterns.
+
+## Decision
+**Four retrieval modes, each optimized for a different query pattern:**
+
+1. **Key-Value** — "What did I decide about X?" → exact match, deterministic, instant.
+2. **Semantic** — "What do I know about pricing?" → similarity search, fuzzy, ranked.
+3. **Graph** — "What's related to Acme Corp?" → traversal, structured relationships.
+4. **Temporal** — "What did I learn yesterday?" → time-filtered scan.
+
+The Context Curator (3.1) combines all four and ranks results by a weighted score.
+
+## Consequences
+- More complex curation logic than a single-mode system.
+- Each mode has its own index (KV, vector, graph, timestamp), increasing storage.
+- Agents get the right answer from the right access pattern instead of one-size-fits-all semantic search.

tulving-0.0.1/docs/adrs/adr-006-decisions-never-decay.md

@@ -0,0 +1,20 @@
+# ADR-006: Decision Memories Never Auto-Decay or Auto-Evict
+
+**Status:** Accepted
+**Date:** 2026-05-04
+**Modules affected:** 1.4, 3.3
+
+## Context
+The decay system reduces importance over time. But some memories are architecturally important to preserve indefinitely — particularly decisions and their reasoning.
+
+## Decision
+**Memories with `type=DECISION` are exempt from automatic decay and automatic eviction. They can only be manually deleted by the agent or developer.**
+
+- Decisions are also exempt from auto-summarization. They are preserved verbatim.
+- An agent can still manually reduce a decision's importance or delete it.
+- This ensures that an agent can always answer "why did I choose X?" even weeks later.
+
+## Consequences
+- Decision entries accumulate over time. For very long-running projects, this could become large.
+- The developer can explicitly archive old decisions if storage is a concern.
+- The curation system still ranks decisions by relevance — old irrelevant decisions won't dominate the context window.

tulving-0.0.1/docs/adrs/adr-007-json-serializable-content.md

@@ -0,0 +1,16 @@
+# ADR-007: Memory Content is Always String, Metadata is JSON-Serializable
+
+**Status:** Accepted
+**Date:** 2026-05-04
+**Modules affected:** 1.4, 1.1
+
+## Context
+Memories need to be embeddable (for semantic search), serializable (for export/import), and displayable (in curated context). Binary data, Python objects, and non-text content break all three.
+
+## Decision
+**`MemoryEntry.content` is always `str`. All metadata fields (tags, relationships, source) are JSON-serializable.** No binary data, no Python objects, no file references.
+
+## Consequences
+- Simple, predictable data model. Every memory can be embedded, exported, and displayed.
+- Agents that need to reference files store the path/URL as a string, not the file itself.
+- Structured data should be serialized to a readable string format before storing (e.g., JSON dump of a dict).

tulving-0.0.1/docs/adrs/adr-008-agent-id-trust-model.md

@@ -0,0 +1,21 @@
+# ADR-008: Agent Identity Trusted from Orchestrator, Not Authenticated
+
+**Status:** Accepted
+**Date:** 2026-05-04
+**Modules affected:** 4.4, 4.1
+
+## Context
+Multi-agent memory requires knowing which agent is reading/writing. But Tulving is a library, not a service — it has no login system, no tokens, no auth server.
+
+## Decision
+**Tulving trusts the `agent_id` provided by the caller. It does not authenticate agents.**
+
+- The orchestrator (Kairos, custom code, MCP server) is responsible for providing the correct agent_id.
+- Tulving enforces scoping rules based on the provided agent_id, but does not verify identity.
+- All operations are logged in the audit trail with the provided agent_id.
+
+## Consequences
+- Simple integration: no auth overhead.
+- A malicious caller can impersonate any agent by providing a fake agent_id.
+- This is acceptable because Tulving runs locally or within a trusted environment. If the caller is compromised, auth wouldn't help — they're already in the process.
+- For hosted/remote deployments (future), a token-based auth layer should be added at the transport level (MCP server or API gateway), not at the Memory class level.

tulving-0.0.1/docs/adrs/adr-009-summarization-archives-not-deletes.md

@@ -0,0 +1,21 @@
+# ADR-009: Summarization Archives Originals, Never Destroys
+
+**Status:** Accepted
+**Date:** 2026-05-04
+**Modules affected:** 3.2, 3.3
+
+## Context
+When old memories are summarized into a digest, what happens to the originals? Deleting them saves space but is irreversible. Keeping them doubles storage.
+
+## Decision
+**Summarized entries are archived (soft-deleted), never hard-deleted. Archived entries are excluded from search and curation but remain in storage for recovery.**
+
+- The summary entry links to its source entries via `relationships`.
+- Archived entries can be unarchived manually.
+- Hard-delete is available but must be explicitly called: `memory.delete(key, hard=True)`.
+- A `purge_archived` CLI command handles bulk cleanup when storage is a concern.
+
+## Consequences
+- No data loss from automatic processes. All summarization is recoverable.
+- Storage grows over time. For very long-running projects, periodic purging may be needed.
+- Archived entries do not appear in search results, curated context, or key listings.

tulving-0.0.1/docs/adrs/adr-010-security-first.md

@@ -0,0 +1,31 @@
+# ADR-010: Security as a First-Class Concern
+
+**Status:** Accepted
+**Date:** 2026-05-04
+**Modules affected:** All
+
+## Context
+Memory content may include sensitive data: API keys observed during work, personal information, credentials in error messages, proprietary business logic. Tulving must handle this safely.
+
+## Decision
+**Security controls are mandatory, enforced in code, never deferred. Same stance as Kairos ADR-016.**
+
+### Mandatory Controls
+
+1. **Sensitive key redaction.** Keys matching `DEFAULT_SENSITIVE_PATTERNS` (password, secret, token, key, credential, auth, api_key, private) are redacted in all exports, MCP tool responses, and curated context output. Raw values accessible only via direct `memory.get()`.
+
+2. **Content sanitization.** Memory content is always `str` (ADR-007). No executable objects in storage.
+
+3. **Path sanitization.** Memory paths, export file paths, and any file I/O validate against traversal attacks. Same rules as Kairos.
+
+4. **Credential security.** Embedding and LLM adapter credentials from environment variables only. Inline credentials raise `SecurityError`.
+
+5. **MCP server security.** Local-only binding. No network exposure. Memory path validated.
+
+6. **Scope enforcement.** Multi-agent scoping raises `SecurityError` on unauthorized access, not silent empty results.
+
+7. **Audit trail.** All store/read/update/delete operations logged with agent_id and timestamp.
+
+## Consequences
+- Every security control has tests in `tests/test_security.py`.
+- Secure defaults. Insecure modes (e.g., disabling redaction) require explicit opt-in.

tulving-0.0.1/docs/adrs/adr-011-kairos-as-sibling-not-dependency.md

@@ -0,0 +1,21 @@
+# ADR-011: Kairos is a Sibling, Not a Dependency
+
+**Status:** Accepted
+**Date:** 2026-05-04
+**Modules affected:** 5.1
+
+## Context
+Tulving and Kairos are natural complements. But making Tulving depend on Kairos (or vice versa) would force users to install both even if they only want one.
+
+## Decision
+**Tulving has zero dependency on Kairos. The Kairos integration (Module 5.1) is an optional extra: `pip install tulving[kairos]`.**
+
+- Tulving works standalone. It doesn't need Kairos to function.
+- Kairos works standalone. It doesn't need Tulving to function.
+- When both are installed, `TulvingPlugin` provides seamless integration.
+- The integration code lives in `tulving/integrations/kairos.py` and imports Kairos conditionally.
+
+## Consequences
+- Users can adopt one without the other.
+- The integration module must handle the case where Kairos is not installed (graceful import error).
+- Both SDKs share the same design philosophy (model-agnostic, security-first, Python-first) but have independent release cycles.

tulving-0.0.1/docs/adrs/adr-012-mcp-tool-design.md

@@ -0,0 +1,30 @@
+# ADR-012: MCP Tools Designed for Agent Ergonomics
+
+**Status:** Accepted
+**Date:** 2026-05-04
+**Modules affected:** 5.6
+
+## Context
+The MCP server exposes Tulving as tools that Claude Code (or any MCP client) calls. Tool design directly impacts how naturally an agent uses memory.
+
+## Decision
+**Tools are designed for how agents think, not how the SDK is structured.**
+
+### Design Principles
+
+1. **Descriptive names.** `memory_store`, `memory_search`, `memory_curate` — not `create_entry`, `vector_search`, `build_context`. The names match what an agent would naturally say: "let me store this" / "let me search for that."
+
+2. **Minimal required parameters.** Only `content` + `type` required for `memory_store`. Everything else is optional with sensible defaults. An agent shouldn't need to think about importance scores or tags for a quick note.
+
+3. **Rich optional parameters.** When the agent wants precision — specific tags, importance, key — the parameters are available but not forced.
+
+4. **Context-ready output.** `memory_curate` returns formatted text ready to use as context, not raw JSON that the agent must parse and format. `memory_search` returns entries with relevance scores.
+
+5. **One tool per intent.** `memory_store` and `memory_get` are separate tools, not one `memory_crud` tool with an `action` parameter. Each tool maps to one thing the agent wants to do.
+
+6. **Tool descriptions guide agent behavior.** Descriptions include when and why to use the tool, not just what it does. Example: "Store a memory — a fact, decision, observation, or plan — for later retrieval."
+
+## Consequences
+- Tool count is higher (8 tools) than a minimal API would require.
+- Each tool is simple and single-purpose — the agent doesn't need to read complex schemas.
+- Claude Code and other MCP clients will naturally discover and use the right tool for the right situation.

tulving-0.0.1/docs/adrs/adr-013-session-detection.md

@@ -0,0 +1,32 @@
+# ADR-013: Three-Layer Session Detection with Graceful Degradation
+
+**Status:** Accepted
+**Date:** 2026-05-04
+**Modules affected:** 3.5, 5.1, 5.6, Memory class
+
+---
+
+## Context
+
+Tulving is used in three modes: as a standalone Python SDK, as a Kairos plugin, and as an MCP server for Claude Code. Each mode has different session boundary signals. A standalone SDK has no natural "session ended" event — the developer's process might exit without warning.
+
+Without session management, memory grows unbounded and end-of-session summarization never triggers.
+
+## Decision
+
+**Three session boundary mechanisms, layered from most reliable to least:**
+
+1. **Explicit API** — `memory.session_start()` / `session.end()` or `with memory.session():` context manager. Works in all modes. The developer controls the boundary.
+
+2. **Integration hooks** — MCP server shutdown (SIGTERM/SIGINT) and Kairos `on_workflow_complete` call `session.end()` internally. Automatic for those modes.
+
+3. **Activity-gap detection** — On next `Memory.__init__`, detect unclosed sessions by checking for `status=ACTIVE` sessions with no recent activity (configurable `inactivity_threshold`, default 30 minutes). Run end-of-session summarization on the abandoned session's memories. Automatic fallback for ungraceful exits.
+
+Each layer degrades gracefully to the next. If the developer calls `session.end()`, that's the boundary. If they don't but the MCP server shuts down cleanly, the hook handles it. If the process crashes, activity-gap detection catches it on next startup.
+
+## Consequences
+
+- Every mode gets session management — no mode is left without lifecycle support.
+- Explicit API is the preferred path, documented prominently.
+- Activity-gap detection introduces a small delay on startup (scanning for abandoned sessions). Acceptable for the reliability it provides.
+- The 30-minute default threshold may misidentify long pauses during active work as session boundaries. Configurable via `LifecycleConfig.inactivity_threshold`.

tulving-0.0.1/docs/adrs/adr-014-contradiction-detection.md

@@ -0,0 +1,30 @@
+# ADR-014: Contradiction Detection Flags, Not Blocks
+
+**Status:** Accepted
+**Date:** 2026-05-04
+**Modules affected:** 3.5, 1.2
+
+---
+
+## Context
+
+Agents store facts that may later become incorrect or contradicted by new information. The system needs to handle the case where "Acme has 3 products" is stored on Monday and "Acme has 5 products" is stored on Thursday.
+
+Two approaches: block the conflicting store and force resolution, or accept the store and flag the contradiction.
+
+## Decision
+
+**Contradictions are detected and flagged, not blocked.** The default policy is `flag`.
+
+- **Key collisions** (same key, new value): the old entry is archived with a `superseded` tag, the new entry is stored with a `supersedes:{old_id}` relationship. This is an upsert — deterministic, no ambiguity.
+
+- **Semantic contradictions** (different keys, conflicting content): detected by checking semantic similarity on store. If similarity > 0.85 and content diverges, both entries are tagged `contradiction:unresolved`. The agent or developer resolves manually.
+
+- **Staleness**: memories not accessed for `staleness_threshold_days` (default 30) are tagged `potentially_stale`. The curator annotates them with age when included in curated context. The agent sees the warning and can verify, update, or discard.
+
+## Consequences
+
+- Stores never fail due to contradictions — the system is always accepting.
+- Contradictions surface as tags, not errors — the agent or developer decides resolution.
+- Staleness is a soft signal, not a hard rule — old memories are deprioritized, not deleted.
+- The `ask` contradiction policy is available for high-stakes scenarios where the developer wants the store to pause and return the contradiction for explicit resolution.