Initialize totem for a project. Creates .totem/ directory and DB if missing.

Args: project: Optional project root path. Auto-detected from git root if omitted.

Create a new memory item.

Args: type: One of: decision, invariant, gotcha, rejected_idea, assumption, open_question, ambiguity, contract, constraint, hypothesis, observation, bug, architecture, implementation title: Short title for the memory statement: The factual claim being stored tags: At least one tag for categorization details: Optional additional details confidence: 0 to 1, default 1.0 importance: 0 to 1, default 0.5 evidence: List of evidence objects with path, startLine, endLine, contentHash related_memory_ids: IDs of related memory items metadata: Extra metadata. Decision items accept 'rationale' (strongly recommended: explain WHY this decision was made, alternatives considered). Invariant items require 'verificationMethod' and 'condition' project: Optional project root path. Auto-detected from git root if omitted.

Retrieve a memory item by ID with staleness check.

Args: id: The memory item ID include_evidence: Whether to check evidence staleness (default True) project: Optional project root path. Auto-detected from git root if omitted.

Update a memory item. Reason is optional but strongly recommended.

Args: id: The memory item ID reason: Why this update was made (strongly recommended for audit trail; defaults to 'maintenance') title: New title statement: New statement details: New details tags: New tags status: New status (active, potentially_stale, invalidated, resolved, superseded) confidence: New confidence (0-1) importance: New importance (0-1) evidence: New evidence list metadata: New metadata project: Optional project root path. Auto-detected from git root if omitted.

Soft-delete a memory item. Reason is required.

Args: id: The memory item ID reason: Required reason for deletion project: Optional project root path. Auto-detected from git root if omitted.

List memory items with optional filters.

Args: type: Filter by type (decision, invariant, gotcha, rejected_idea) tags: Filter by tags (items must have at least one) status: Filter by status (active, potentially_stale, invalidated) sort: Sort by 'created_at', 'updated_at' (default), or 'importance' limit: Maximum items to return (default 50) project: Optional project root path. Auto-detected from git root if omitted.

List most recently created memories.

Args: limit: Maximum items to return (default 5) project: Optional project root path. Auto-detected from git root if omitted.

List in-progress task memories (tagged with task:*).

Args: limit: Maximum items to return (default 10) project: Optional project root path. Auto-detected from git root if omitted.

List command outcome memories (gotchas tagged with cmd:*).

Args: limit: Maximum items to return (default 20) project: Optional project root path. Auto-detected from git root if omitted.

Mark a conflict as resolved.

Args: conflict_id: The conflict ID resolution: Description of how the conflict was resolved (e.g. 'Kept existing: X') project: Optional project root path. Auto-detected from git root if omitted.

Hybrid tag + full-text search.

Args: query: Search query (full-text via Turso FTS5) types: Filter by memory types tags: Filter by tags include_stale: Whether to include potentially stale items limit: Maximum results (default 20) project: Optional project root path. Auto-detected from git root if omitted.

Assemble engineering context with output ordering.

Pipeline: tag match -> score -> sort -> truncate -> serialize. Conflicts and warnings are NEVER dropped for budget.

Args: tags: Tags to match against task: Optional task description (shown in output header) token_budget: Optional token budget for truncation types: Filter by memory types include_stale: Whether to include potentially stale items current_task: Description of what you're working on right now. Boosts scoring for memories relevant to this task. paths: Filter items whose evidence matches these file paths project: Optional project root path. Auto-detected from git root if omitted.

Export all memories and conflicts as portable JSON.

Args: project: Optional project root path. Auto-detected from git root if omitted.

Import memories from a previously exported dict. Skips duplicate IDs.

Args: data: The export dict containing 'items' and optionally 'conflicts' project: Optional project root path. Auto-detected from git root if omitted.

Register facts learned from reading a file. Auto-hashes content, updates existing or creates new.

Call this after reading a file to store what you learned. Prevents re-reading the same file in future sessions.

Args: path: File path (e.g. 'src/auth.py') statement: What you learned (e.g. 'getUser() returns User | null, takes user_id: int') subject: What the fact is about (e.g. 'getUser()') kind: What kind of code fact (api/function/module/type/config/schema) tags: Tags for categorization start_line: Optional line range start (auto-detected if omitted) end_line: Optional line range end (auto-detected if omitted) title: Optional title (defaults to 'File: {filename}') details: Optional additional details project: Optional project root path. Auto-detected from git root if omitted.

Register a file write/modification. Auto-hashes content, updates existing or creates new.

Call this after editing or writing a file to document what changed and why. The commit-gate hook will block all other tools until you register the write.

Args: path: File path (e.g. 'src/auth.py') statement: What changed (e.g. 'Added input validation to getUser()') reason: Why the change was made (e.g. 'Fix: getUser() crashed on null input') tags: Tags for categorization start_line: Optional line range start end_line: Optional line range end title: Optional title (defaults to 'File: {filename}') details: Optional additional details project: Optional project root path. Auto-detected from git root if omitted.

Create a decision memory. Always provide rationale explaining WHY.

Create an invariant memory. Requires verificationMethod and condition.

Create a gotcha memory for non-obvious behaviors.

Create a rejected idea memory. Prevents re-proposing dead ends.

Create an assumption memory. classify: fact/assumption/hypothesis/guarantee.

Create an open question memory. impact: low/medium/high/critical.

Create an ambiguity memory. impact: low/medium/high/critical. high/critical = blocking.

Flag an ambiguity. Convenience wrapper for ambiguity_create. impact: low/medium/high/critical.

Create a contract memory for observable behavior of functions/APIs.

Create a constraint memory for implementation restrictions.

Create a hypothesis memory. Never auto-promote to invariant/decision.

Create an observation memory. Never auto-promote to invariant/decision.

Create a bug memory. State machine: open→confirmed→fixed→verified.

Create an architecture memory for component structure mapping.

Create an implementation memory for codebase facts (API, function, module, type, config, schema).