totem

Totem stands watch over what a tribe has learned. It does the same for your codebase.

A totem stands watch over what a tribe has learned. Totem does the same for a codebase. It's a Git-aware memory server for coding agents: decisions, invariants, and gotchas persist across sessions, backed by evidence, and flagged the moment the code underneath them changes.

Why

AI coding agents lose engineering context between sessions. They re-discover the same gotchas, re-debate the same decisions, and forget invariants that were already established. totem persists this knowledge locally and serves it back to agents as structured context, ordered by relevance.

Install

Requires Python 3.13+.

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

The npx command auto-installs or upgrades the Python MCP server, pins its version, and configures enforcement plugins for OpenCode, Claude Code, and Kimi Code. For Kimi Code it also registers a user-level MCP entry (~/.kimi-code/mcp.json) so totem is available in every project.

Supported agents

Features

• 14 memory types with type-specific metadata validation
• 31 MCP tools (16 core + 15 typed wrappers)
• Staleness detection via SHA256 content hashing on evidence
• Conflict detection on overlapping evidence and contradictory claims
• Full-text search via Turso FTS5
• Hybrid memory (project + user databases)
• Context assembly with scored pipeline and token budget
• Agent enforcement blocks reads/grep/bash when memory exists, forces search-first workflow
• Commit gates block all tools until agent registers file reads and writes
• History audit on every create, update, and delete

How it works

Agent reads file for the first time
  → commit-gate blocks → agent registers read → memory stored → done

Agent reads file again (memory exists)
  → blocked → redirected to memory tools
  → searches memory → finds context → done

Agent writes a file
  → commit-gate blocks → agent registers write with reason → change documented → done

Agent reads file but finds nothing in memory
  → allowed to read → commit-gate requires registration → done

Setup

OpenCode

Add to ~/.config/opencode/opencode.json (or let npx @emiliano-go/totem write it):

{
  "plugin": ["@emiliano-go/totem"],
  "mcp": {
    "totem": {
      "type": "local",
      "command": ["uvx", "totem-mcp==<version>"],
      "enabled": true
    }
  }
}

The installer pins <version> to the npm package version and pre-warms the uvx cache, so agent startups use the cached environment and never hit the network.

Claude Code

claude mcp add totem -- totem-mcp

Kimi Code

MCP server and hooks are auto-configured by npx @emiliano-go/totem: the MCP server goes in user-level ~/.kimi-code/mcp.json (every project), and the hooks go in ~/.kimi-code/config.toml.

Manual setup

If you prefer manual configuration:

# Initialize totem in your project
totem init

# For a different project
totem init --project /path/to/other

Quick start

MCP tools (from your agent)

# Store a decision
memory_create_tool(type="decision", title="Use FTS5 for search",
  statement="SQLite FTS5 is sufficient for our search needs",
  tags=["search", "sqlite"],
  metadata={"rationale": "No external dependency needed"})

# Get full context for a task
engineering_context_tool(tags=["api", "database"],
  current_task="Adding JWT refresh endpoint")

# Search memory
memory_search_tool(query="authentication", tags=["auth"])

# Store a command outcome
memory_create_tool(type="gotcha", title="uv pip install -e . works",
  statement="Editable install works with uv pip on PEP 668 systems",
  tags=["cmd:uv-pip-install", "python"])

CLI

# Create a memory item
totem create --type decision --title "Use FTS5 for search" \
  --statement "SQLite FTS5 is sufficient for our search needs" \
  --tags "search,sqlite" --metadata '{"rationale": "No external dependency needed"}'

# Search
totem search --query "FTS5" --tags "sqlite"

# Assemble context
totem context --tags "search,sqlite" --current-task "Implementing search" --budget 4096

# Export/import
totem export -o backup.json
totem import backup.json

Memory types

MCP tools (31)

CLI commands (14)

Context assembly

Scoring formula:

score = 0.30*tag_match + 0.20*task_similarity + 0.25*importance
      + 0.15*confidence + 0.10*recency

Invariants, constraints, and ambiguities get a 1.25x multiplier. Potentially stale items get a 0.5x penalty.

Output sections (BLOCKING AMBIGUITIES, CONFLICTS, and STALE WARNINGS are never budget-truncated):

1. TASK (if provided)
2. BLOCKING AMBIGUITIES
3. CONTEXT CONFLICTS
4. CRITICAL CONSTRAINTS
5. CRITICAL INVARIANTS
6. RELEVANT CONTRACTS
7. ARCHITECTURE
8. DECISIONS
9. KNOWN AMBIGUITIES (non-blocking)
10. OBSERVATIONS
11. GOTCHAS
12. KNOWN BUGS
13. HYPOTHESES
14. CODEBASE FACTS
15. OPEN QUESTIONS
16. REJECTED IDEAS
17. STALE KNOWLEDGE WARNINGS

Workspace scoping

totem auto-detects your project root via git rev-parse --show-toplevel. Override with --project <path> on any CLI command or project parameter on any MCP tool.

Hybrid memory

• Project memories: .totem/totem.db
• User memories: ~/.local/share/totem/totem.db

engineering_context searches both, with project memories taking precedence.

Deployment boundary

Totem is a single-user, local memory layer. It has no tenancy or authorization model, and this is intentional:

• the user DB lives at ~/.local/share/totem/totem.db, owned by the OS user that runs totem (override with TOTEM_USER_DB);
• the project DB lives in the project's .totem/ directory, scoped to whoever can read the checkout;
• MCP tools run with the full privileges of that user.

Do not expose a totem MCP server to multiple untrusted users on one host, and do not point several OS users at one shared user DB. If you need multi-user isolation, run one totem instance (and one user DB) per user. The boundary is enforced by the filesystem and the OS user, not by totem itself.

Tag conventions

• task:<name>: In-progress work. Query with memory_tasks_tool.
• cmd:<command>: Command outcomes. Query with memory_commands_tool.
• architecture:<module>: Structural facts about a module.
• outcome:<what>: Measurable results (performance wins, bug fix impact, etc.).

Companion skill

The skills/precision-first/ directory contains a precision-first software engineering methodology designed to pair with totem.

Development

# Run JS tests
cd plugins/totem-enforce && node test-tokenize.js

# Run Python package tests
uv run pytest

# Run Python hook tests
cd plugins/totem-enforce && python3 test-enforce.py

License

MIT