totem

Persistent memory layer for engineering agents. Store decisions, invariants, gotchas, and rejected ideas in a local Turso database with staleness detection, conflict detection, full-text search, and structured context assembly.

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.

Features

• Four memory types: decision, invariant, gotcha, rejected_idea (each with type-specific metadata)
• Staleness detection: SHA256 content hashing on linked evidence; auto-transitions items to potentially_stale when source code changes
• Conflict detection: surfaces contradictory decisions or invariants on overlapping code ranges
• Conflict resolution: mark conflicts as resolved and pick a winner
• Full-text search: Turso FTS5 on title, statement, details, and tags
• Hybrid memory: project memories in .totem/, user memories in ~/.local/share/totem/. Context assembly searches both.
• Context assembly: scored pipeline with token budget support, section ordering per spec
• Workspace scoping: auto-detects git root for correct DB placement; explicit --project override available
• Export/import: move memories between machines or seed a new project from an existing one
• MCP server: expose all tools via Model Context Protocol for agent use
• CLI: full command-line interface for manual operations

Install

Requires Python 3.13+.

git clone https://github.com/emiliano-go/totem.git
cd totem

# With uv (recommended)
uv sync

# Or with pip
pip install .

This installs two entry points: totem (CLI) and totem-mcp (MCP server).

Add to your agent

Claude Code:

claude mcp add totem -- uvx totem-mcp

opencode (add to ~/.config/opencode/opencode.json):

{
  "mcp": {
    "totem": {
      "type": "local",
      "command": ["uvx", "totem-mcp"],
      "enabled": true
    }
  }
}

Claude Desktop / Cursor / Windsurf (add to config):

{
  "mcpServers": {
    "totem": {
      "command": "uvx",
      "args": ["totem-mcp"]
    }
  }
}

VS Code (add to .vscode/mcp.json):

{
  "servers": {
    "totem": {
      "type": "stdio",
      "command": "uvx",
      "args": ["totem-mcp"]
    }
  }
}

Project-scoped (Claude Code / Cursor / opencode, checked into repo):

The included .mcp.json handles this automatically. Just open your project and the agent picks it up.

Quick start

MCP server

Start the server:

totem-mcp

Then use it from your agent. Example tool calls:

memory_create_tool(type="invariant", title="No direct DB access in API layer",
  statement="API handlers must use the repository layer, never sqlite3 directly",
  tags=["api", "database"], metadata={"verificationMethod": "code review",
  "condition": "No sqlite3 imports in src/api/*.py"})

engineering_context_tool(tags=["api", "database"], task="Refactor auth middleware")

CLI

# Create a memory item (rationale is optional but strongly recommended)
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 search dependency needed"}'

# Get it back
totem get <ITEM_ID>

# Search (full-text + tags)
totem search --query "FTS5 search" --tags "sqlite"

# List recent items
totem recent

# Resolve a conflict
totem resolve <CONFLICT_ID> --resolution "Kept existing: Use FTS5"

# Export all memories to a file
totem export -o backup.json

# Import memories from a file
totem import backup.json

# Assemble context for a task
totem context --tags "search,sqlite" --task "Add fuzzy search" --budget 4096

MCP tools

All tools return JSON strings. Every tool accepts an optional project parameter to override workspace scoping.

CLI commands

All commands accept --project <path> to override workspace scoping.

All commands output JSON to stdout.

Workspace scoping

totem auto-detects your project root using git rev-parse --show-toplevel. The .totem/totem.db file is created relative to the git root, not your current working directory. This means the MCP server works correctly regardless of which subdirectory it starts in.

To override auto-detection, pass --project <path> on any CLI command or project parameter on any MCP tool.

Memory types

Each type captures a different kind of engineering knowledge:

Hybrid memory

totem stores memories in two locations:

• Project memories: .totem/totem.db (in your repo, checked into version control or gitignored)
• User memories: ~/.local/share/totem/totem.db (personal preferences, global patterns)

engineering_context searches both databases, with project memories taking precedence. This means your agent remembers project-specific decisions and your personal coding preferences across all projects.

Export and import

Move memories between machines or seed a new project:

# Export everything from the current project
totem export -o project-memories.json

# Import into a different project
cd /path/to/other-project
totem import ../project-memories.json

Import skips items with duplicate IDs and reports counts of imported vs skipped items.

Context assembly

The engineering_context tool runs a scored pipeline across both project and user memories:

Scoring formula:

score = 0.4 * tag_match + 0.3 * importance + 0.2 * confidence + 0.1 * recency

Invariants get a 1.25x multiplier. Potentially stale items get a 0.5x penalty.

Output section order (never truncated):

1. TASK (if provided)
2. BLOCKING AMBIGUITIES (high/critical impact, always shown)
3. CONFLICTS (always shown)
4. CRITICAL INVARIANTS
5. DECISIONS
6. GOTCHAS
7. REJECTED IDEAS
8. STALE WARNINGS (always shown)

Conflicts and warnings are never dropped due to token budget. Item sections truncate when budget is exceeded, with a count of omitted items noted.

Data model

Core fields on every MemoryItem:

Evidence entries link to source code ranges with SHA256 hashes for staleness detection.

Companion skill

The skills/precision-first/ directory contains a precision-first software engineering methodology designed to pair with totem. It covers invariant management, ambiguity classification, contradiction detection, and structured code review workflows.

Development

git clone https://github.com/emiliano-go/totem.git
cd totem
uv sync

# Run tests (none yet)
uv run pytest

# Run CLI
uv run totem --help

# Run MCP server
uv run totem-mcp

License

MIT