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 the Python MCP server and configures enforcement plugins for OpenCode, Claude Code, and Kimi Code.

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:

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

Claude Code

claude mcp add totem -- uvx totem-mcp

Kimi Code

Hooks are auto-configured by npx @emiliano-go/totem.

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.

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 tests
cd plugins/totem-enforce && python3 test-enforce.py

License

MIT