v0.10.1

Totem v0.10.1

Fixes

• memory_graph now filters by entity before applying the result limit, so a file or symbol outside the first page still resolves.

Tests

• 211 Python tests pass.
• 35 dsh-totem tests pass.

Install

pipx install --force "totem-mcp[embeddings]==0.10.1"

v0.10.0

Totem v0.10.0

TL;DR

Totem now has the full memory operating loop: read-side file memory, linked sessions, quality reporting, typed memory classes, an entity graph with bi-temporal edges, hierarchical rollups, heat and decay, workflow memory, Markdown interchange, and a maintenance cycle. Schema v12 migrates existing databases in place.

P0: read path and signal

• Whole-file reads check the cached TLDR first and return the TLDR, language, and symbol outline when the content hash matches. force: true reads the body.
• Session summaries link to the file-state records they touched with a touches relation.
• memory_quality and totem quality report signal ratio, classes, provenance, stale evidence, conflicts, duplicates, relations, checks, feedback, embeddings, entities, and digest composition.
• Conflict detection requires a shared subject plus opposing claims. Shared evidence alone is not a conflict.

P1: memory structure

• Memory classes: operational, episodic, procedural, core, and semantic.
• Entity graph: files, symbols, components, rules, pull requests, and packages are linked to memories.
• Bi-temporal relations: recorded time, validity windows, and source episode on every edge.
• Hierarchical rollups: file TLDRs feed module summaries and a project map.
• Heat and decay: recency, importance, and access produce a heat score; old low-importance operational and episodic memories can be archived.
• memory_profile stores always-on core profile blocks in the user database.

P2: lifecycle and portability

• memory_workflow stores reusable procedures with preconditions, verification, and failure modes.
• memory_induce_workflow drafts a procedure from a session summary.
• memory_maintenance and totem maintain run entity backfill, revalidation, rollup, decay, and consolidation.
• totem export-markdown and totem import-markdown preserve statements, details, evidence, and wikilink relations.
• A five-case LongMemEval-style suite covers extraction, multi-session reasoning, temporal reasoning, knowledge updates, and abstention.

Schema v12

• access_count and last_accessed_at on memory items.
• recorded_at, valid_from, valid_to, and source_episode on relations.
• memory_entities and memory_entity_links tables.

The TrustSight corpus migrated in place and was rolled up into 18 module summaries plus a project map.

Tests

• 211 Python tests pass.
• 35 dsh-totem tests pass.
• 61 MCP tools and 39 CLI commands.

Install

pipx install --force "totem-mcp[embeddings]==0.10.0"

v0.9.3

Totem v0.9.3

TL;DR

File memory now serves cached TLDRs before a whole-file read, session summaries link to the files they touched, and totem quality reports whether the corpus is durable knowledge or activity noise. Conflict detection is stricter: shared evidence alone is no longer a contradiction.

Read-side file memory

• A whole-file read checks the file-state TLDR first.
• When the content hash matches, the agent gets the TLDR, language, and symbol outline instead of the file body.
• Pass force: true to read the full body.
• The response reports lineCount, so the model knows the size of the skipped file.

Session links

• memory_session_summary links each summary to the file-state records it touched with a touches relation.
• Path activation can now find the session that explains a file change.

Quality report

• New memory_quality_tool and totem quality.
• Reports signal ratio, type mix, provenance coverage, stale evidence, conflicts, duplicate titles, relations, checks, feedback, embeddings, and digest composition.

Conflict precision

• Overlapping evidence alone no longer creates a conflict.
• A conflict requires a shared subject plus opposing claims: negation, a changed number, or high statement similarity.
• The four false conflicts in the TrustSight corpus were resolved as distinct claims.

Tests

• 197 Python tests pass.
• 35 dsh-totem tests pass.

Install

pipx install --force "totem-mcp[embeddings]==0.9.3"

totem v0.9.2

TL;DR

totem v0.9.2 adds file-state memory. Reads and writes now produce one deterministic TLDR per file, keyed by content hash, instead of an append-only activity log. A new session summary captures what changed and why in one record. dsh-totem consumes both, and the first-step digest filters file state so decisions and gotchas are no longer buried by Patched <file> rows. 192 Python tests pass.

---

File-state TLDR

• memory_file_context reads one file, stores its current state, and returns fresh, changed, tldr, symbols, and blobHash.
• An unchanged file returns fresh: true without writing a new row.
• A changed file updates the same record in place.
• Summaries are deterministic and local: Python AST, Markdown headings, JSON/YAML keys, JavaScript exports, and shell functions. No model call and no network.
• Evidence paths are project-relative and carry a whole-file blob hash.

Session summaries

• memory_session_summary creates or updates one summary per session.
• It records the changed paths, the work description, and the commit when available.
• Repeated turns update the same record instead of appending one record per turn.

Search and digest hygiene

• File-state TLDRs are excluded from generic memory_search by default.
• include_file_state is available when file state is the target.
• The dsh-totem first-step digest filters file-state rows and keeps decisions, gotchas, contracts, architecture, observations, and tasks.

dsh-totem integration

• Reads call memory_file_context; they no longer store Read <name> markers.
• Writes update the file-state TLDR; they no longer append Patched <name> fallbacks.
• Symbol memories from the distiller are still created when available.
• Turn end creates one session summary from the changed paths and assistant text.

Backfill

• totem files backfill previews legacy file-change conversion.
• totem files backfill --apply converts records whose source file still exists.
• --prune-missing deletes legacy file records whose source file is gone.

Tests

• 192 Python tests pass.
• 32 dsh-totem tests pass.

Install

pip install 'totem-mcp[embeddings]==0.9.2'

totem v0.9.1

TL;DR

totem v0.9.1 fixes one temporal validity edge case found during full manual testing. include_expired now re-admits only claims whose validity window has ended; claims whose valid_from is still in the future stay out of context and search until as_of reaches them. 182 Python tests pass.

---

Fixes

• Future-dated claims: include_expired no longer releases claims that have not started yet.
• Temporal state: candidates now distinguish current, future, and expired instead of collapsing both non-current states into one flag.
• Regression coverage: a new test asserts future exclusion with include_expired, inclusion at a later as_of, and normal expired handling.

Manual verification

A disposable environment in /tmp exercised:

• fresh schema v11 and migration from a real 0.8.0 database;
• create, get, update, search, context, list, recent, tasks, commands, timeline;
• check-backed verification, audit, revalidation, conflict resolution, and GC;
• temporal filtering, path activation, budget caps, abstention, and user DB scope;
• feedback, reranker training, and near-duplicate consolidation;
• export format v2, import, replace import, and check preservation;
• CLI commands, MCP server tools, hardening limits, and concurrent creates;
• static Model2Vec embeddings and the hash fallback without the optional package.

Tests

• 182 Python tests pass.

Install

pip install 'totem-mcp[embeddings]==0.9.1'

totem v0.9.0

TL;DR

totem v0.9.0 rebuilds retrieval around corpus-wide candidates. Context and search now fuse lexical, dense, path, symbol, tag, and relation signals instead of starting from tag-filtered rows. It adds temporal validity, feedback-driven reranking, abstention, near-duplicate consolidation, and richer evaluation. 181 Python tests pass.

---

Retrieval

• Corpus-wide candidates: context and search build candidates from the whole database with FTS (full query and per term), dense vectors, evidence paths, symbols, tags, and a two-hop relation expansion.
• Tags are a boost: tags no longer gate engineering_context; an untagged memory can surface when the task, code path, or a relation makes it relevant.
• Persisted embeddings: static Model2Vec vectors are stored in memory_embeddings and refreshed by content hash. The dependency-free hash encoder remains the fallback and stays in memory.
• Hybrid search: memory_search returns fused scores and the reasons each result entered.

Temporal validity

• valid_from and valid_to are available on create, update, and import.
• Context and search accept as_of and include_expired; expired claims are excluded by default and demoted when included.
• Validity windows are validated, so valid_to must be later than valid_from.

Feedback and learned ranking

• memory_feedback records useful, wrong, irrelevant, verified, or stale signals with an optional query, tags, and weight.
• memory_train_models fits a linear reranker over candidate and trust features, and fits the conformal calibrator when feedback has both classes.
• Trained weights are stored in meta with the commit and example count that produced them. The learned path stays advisory.
• Staleness checks are cached per retrieval, so repeated evidence paths are not re-read during one context build.

Search and abstention

• Context returns abstained: true with an empty body when no memory clears the score threshold (TOTEM_ABSTAIN_SCORE, default 0.12).
• Critical classes, path matches, and stale knowledge still surface, so low scores cannot hide a known hazard.
• memory_search keeps explicit tag filters when tags are supplied, while context treats tags as a signal.

Consolidation

• memory_consolidate clusters near-duplicates by cosine similarity.
• Dry-run is the default; --apply marks duplicates superseded, records a relation to the canonical memory, and appends history.
• Opposite-polarity clusters are flagged as contradiction candidates.

Evaluation and portability

• Eval cases support single, multi, temporal, update, and abstention.
• Reports add nDCG and abstention accuracy alongside recall, MRR, and p95 latency.
• Export format is now v2 and includes recorded checks; v1 exports remain importable.

Schema

• Schema v11 adds memory_embeddings, memory_feedback, and the validity columns.
• Migration 006 adds the objects and postconditions; existing databases upgrade in place.

Tests

• 181 Python tests pass.

Install

pip install 'totem-mcp[embeddings]==0.9.0'

or without the optional encoder:

pip install totem-mcp==0.9.0

The npm package is published by CI.

totem v0.8.0: auditable memory (hash chain, recorded checks, hardened tools)

TL;DR

totem v0.8.0 makes memory claims auditable. History is hash-chained, verification consumes an observed check record instead of a free-text claim, and evidence paths are contained to the project root. Every MCP tool is bounded by output caps, rate limits, and deadlines. Ranking gains a deterministic dense leg fused with FTS, MMR diversification, a linear reranker, and calibrated trust that stays advisory until it beats the deterministic rule on held-out history. 156 tests pass.

---

Evidence and trust

• Tamper-evident history: every memory_history row carries prev_hash, hash, and a state_hash snapshot of the item. totem audit recomputes the chain and exits non-zero on mismatch.
• Recorded checks: memory_check_record / totem check stores command, cwd, exit code, output hash, evidence hash, commit, and run time.
• Evidence-derived verification: memory_verify(check_id=...) requires the check to exist, belong to the item, have exited 0, and match the current evidence digest. Assertion-only verification still works but is marked and surfaced with a warning.
• Path containment: evidence is resolved with realpath and commonpath under the project root; absolute escapes, .. traversal, and symlink escapes are rejected at registration and at staleness reads.
• Write capture: register_file_write records the git-observed changed files and a bounded content digest, so a claimed write that changed nothing is visible.
• Schema v10: checks table plus history chain columns; the migration runs with a postcondition and backfills the chain.

MCP hardening

• Bounded output with a truncated envelope, per-tool token buckets, argument size caps, wall-clock deadlines, and fail-soft JSON errors.
• 42 tools; totem_manifest_tool returns a stable SHA-256 of the surface.

Advisory models

• Platt scaling and split conformal prediction over claim features, with an honest shared-sample mode below 40 rows.
• rule_trust deterministic baseline; totem models validate promotes a calibrated head only on a temporal held-out slice with a better Brier score and coverage within tolerance.
• Deterministic signed-hash TF-IDF encoder, reciprocal-rank fusion with FTS, MMR diversification, and a trainable linear reranker.
• N=1 prior-experience recall exposed as closestId.
• totem eval reports recall@k, MRR, and p95 latency, plus a gate that rejects a recall or MRR regression beyond tolerance or a latency overrun.

CLI

New totem audit, totem check, totem eval, and totem models validate; totem verify --check-id consumes a recorded check.

Tests

156 Python tests pass, including property-based path and fusion checks.

Install

npm install @emiliano-go/totem
npx @emiliano-go/totem

PyPI release is handled by CI.

totem v0.7.0: verification lifecycle (verify, retract, GC, concurrency)

TL;DR

totem v0.7.0 adds a full verification lifecycle: memories can be verified against a real verification record (with commit and timestamp), verification is retracted automatically when the underlying evidence changes, verified memories are surfaced and boosted in context, and enforcement can require verification before trusted claims are used. It also adds a safe GC purge with dry-run, fixes a first-bootstrap race in concurrency, and hardens writes to be multiprocess-safe with unique evidence locators. All 122 commits are now GPG-signed.

---

Verification lifecycle

• Record: verified_at and verified_commit are stored on a memory when it is verified, so verification points at a specific state of the evidence.
• Gate: the enforcement verify gate now requires a real verification record; asserted_by is treated as provenance, not verification.
• Retract: verification is retracted automatically when the evidence changes, so stale claims do not stay marked as verified.
• Surface and boost: context surfaces verified memories and boosts their relevance ranking.
• Bug verification: bugs join the set of verifiable items, with GC exemption and portability across export or import.

Garbage collection

• Safe lifecycle purge with dry-run: preview what would be collected before anything is deleted.

Concurrency and correctness

• Bootstrap race: fixed a stale-snapshot race on first bootstrap in multiprocess use.
• Writes: multiprocess-safe writes with unique evidence locators, backed by real concurrency tests.
• Context cap: max_item_chars caps a single item so one memory cannot dominate the token budget.

Docs

• Architecture diagram in the README "How it works" section, plus refreshed tool and CLI counts.

Tests

• 114 Python tests pass.

Install

npm install @emiliano-go/totem
npx @emiliano-go/totem

PyPI release is handled by CI.

totem v0.6.0: hardening (evidence, atomic writes, hard budget, CI)

TL;DR

totem v0.6.0 is a hardening release. It fixes a false-negative staleness detector in evidence, makes every semantic mutation atomic, turns the context token budget into a hard bound, enforces update and import validation plus the memory lifecycle, constrains relations, makes migrations crash-safe, and adds CI and release gates, typed errors, restorable imports, resource limits, indexed hot paths, audit actors, idempotency, and a configurable enforcement policy. No new memory types.

---

Correctness

• Evidence: symbol evidence is now identity plus content (a normalized body hash). A symbol whose body materially changed is stale; moved-but-unchanged is fresh; legacy rows without symbolHash keep presence-only behaviour. This closes a false negative where a changed implementation stayed fresh.
• Transactions: low-level DB helpers no longer commit. Every semantic mutation (create, update, delete, relate, import, conflict resolve) runs in one transaction and rolls back on failure, so the knowledge graph cannot be left partially applied.
• Validation: memory_update reconstructs and revalidates the item, and memory lifecycle transitions are enforced (illegal transitions rejected). Create, update, and import now apply the same schema invariants.
• Context budget: token_budget is a hard upper bound. Every section is capped, emergency sections report how many were omitted, and engineering_context returns budget, estimatedTokens, and per-section omitted counts.
• Relations: UNIQUE(from_id, to_id, kind), lookup indexes, self, dangling, and cycle rejection, plus idempotent duplicates.

Operational

• Migrations: BEGIN IMMEDIATE lock, one transaction per migration, postcondition verification, and no schema-version stamp on failure. A failed migration rolls back and retries cleanly.
• Hook state: atomic temp plus fsync plus rename, a private 0700 directory with 0600 files, and a TTL sweep.
• Enforcement policy: TOTEM_ENFORCEMENT is off, warn, normal, or strict. Strict fails closed; fail-open events are logged to the hook state directory.
• Typed errors: MCP tools return {error: {code, message}} with codes (NOT_FOUND, INVALID_ARGUMENT, SCHEMA_ERROR, CONFLICT, STALE, DB_UNAVAILABLE, MIGRATION_FAILED, INTERNAL).
• Imports: memory_import gains normal, strict, and replace modes, --dry-run, validation before mutation, and a complete report.
• Resource limits: caps on title, statement, details, tags, metadata, evidence, import size, and token budget.

Scale, relevance, audit

• Indexed hot paths: a statement_normalized column and a locator table remove whole-corpus scans from density dedup and file registration.
• Conflict relevance: context only surfaces conflicts touching considered memories or the critical classes (invariants, constraints, contracts).
• Scope and explainability: task scope boosts only when it matches the current task; context returns a why map for each included memory.
• Audit actors: history records actor, session, source, commit, and request id; relations and conflict resolutions are recorded.
• Idempotency: writes accept an operation_id; a replay returns the stored result instead of re-executing.

Deployment

• Totem is a single-user, local memory layer with no tenancy. The boundary is documented in the README and the db module docstring; run one instance and one user DB per OS user.

CI and tests

• New .github/workflows/ci.yml: pytest on Python 3.13 and 3.14, CLI smoke, MCP server startup, build artifacts, and an npm package job. Publishing workflows now depend on CI.
• 89 Python tests pass.

Install

npm install @emiliano-go/totem
npx @emiliano-go/totem

PyPI release is handled by CI.

totem v0.5.1: pinned MCP versioning, hook batching, Kimi auto-wiring

Installer (bin/totem.js)

• MCP server is registered as uvx totem-mcp==<npm package version> (pinned to the release) and pre-warmed during npx totem, so agent startups use the cached uvx environment and never hit the network. Falls back to the totem-mcp PATH binary when uvx is unavailable or the pin cannot be resolved. Supersedes the 0.5.0 "PATH binary so local installs take effect immediately" behavior for released versions.
• Installer now upgrades stale installs: compares totem --version against the package version and runs pipx upgrade / uv tool upgrade / pip install --upgrade on mismatch (previously it only checked presence, so installs never moved off old versions).
• Registers the totem MCP server in Kimi Code's user-level ~/.kimi-code/mcp.json so totem is available in every project (project-level .mcp.json still overrides).
• Wires the enforcement hooks into Kimi Code's ~/.kimi-code/config.toml (PreToolUse/PostToolUse/UserPromptSubmit → totem-hook.py pre|post|clear). Idempotent, TOML-safe append; strips legacy per-script totem hook entries.
• Fixed: crash with a raw stack trace when the CLI was installed but its bin dir was not on PATH (execSync("totem --version") was uncaught); now prints a clear error and exits 1.

Enforcement hooks

• Memory gates cost ONE totem search subprocess per tool call: terms are batched into a single FTS5 OR query capped at 5, instead of one subprocess per word (a miss spawned one cold Python process per word, which flooded the process table under parallel tool calls).
• Non-blocking per-session flock on all hooks: concurrent invocations fail open instead of stacking subprocesses.
• Legacy totem-enforce.py/totem-store-read.py: same batching/lock fixes applied.