totem-mcp 0.1.0__tar.gz

totem_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,315 @@
+Metadata-Version: 2.3
+Name: totem-mcp
+Version: 0.1.0
+Summary: Persistent memory layer for engineering agents
+Author: Emiliano Gandini Outeda
+Author-email: Emiliano Gandini Outeda <emiliano.gandini@protonmail.com>
+Requires-Dist: pydantic>=2.0,<3.0
+Requires-Dist: click>=8.0,<9.0
+Requires-Dist: mcp>=1.0,<2.0
+Requires-Dist: pyturso>=0.7.2
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# totem
+
+<p align="center">
+  <a href="https://pypi.org/project/totem-mcp/">
+    <img src="https://img.shields.io/pypi/v/totem-mcp?logo=pypi&logoColor=white&style=for-the-badge" alt="PyPI">
+  </a>
+  <a href="https://pypi.org/project/totem-mcp/">
+    <img src="https://img.shields.io/pypi/pyversions/totem-mcp?logo=python&logoColor=white&style=for-the-badge" alt="Python">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-10AC84?style=for-the-badge" alt="License">
+  </a>
+  <a href="https://modelcontextprotocol.io">
+    <img src="https://img.shields.io/badge/MCP-Compatible-8A2BE2?logo=modelcontextprotocol&logoColor=white&style=for-the-badge" alt="MCP">
+  </a>
+
+</p>
+
+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+.
+
+```bash
+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:**
+```bash
+claude mcp add totem -- uvx totem-mcp
+```
+
+**opencode** (add to `~/.config/opencode/opencode.json`):
+```json
+{
+  "mcp": {
+    "totem": {
+      "type": "local",
+      "command": ["uvx", "totem-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+**Claude Desktop / Cursor / Windsurf** (add to config):
+```json
+{
+  "mcpServers": {
+    "totem": {
+      "command": "uvx",
+      "args": ["totem-mcp"]
+    }
+  }
+}
+```
+
+**VS Code** (add to `.vscode/mcp.json`):
+```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:
+
+```bash
+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
+
+```bash
+# 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.
+
+| Tool | Description |
+|------|-------------|
+| `memory_create_tool` | Create a memory item. Provide `rationale` in metadata for decisions (strongly recommended). |
+| `memory_get_tool` | Retrieve by ID with staleness check |
+| `memory_update_tool` | Update any field. Provide `reason` (strongly recommended for audit trail). |
+| `memory_delete_tool` | Soft-delete (requires `reason`) |
+| `memory_list_tool` | Filtered listing with `sort` param (`created_at`, `updated_at`, `importance`) |
+| `memory_recent_tool` | List most recently created memories (default limit 5) |
+| `memory_search_tool` | FTS5 full-text search (includes tags) with type/tag filters |
+| `resolve_conflict_tool` | Mark a conflict as resolved with a resolution description |
+| `engineering_context_tool` | Scored context assembly; searches project + user DBs |
+| `memory_export_tool` | Export all memories and conflicts as portable JSON |
+| `memory_import_tool` | Import memories from an export dict (skips duplicate IDs) |
+
+## CLI commands
+
+All commands accept `--project <path>` to override workspace scoping.
+
+| Command | Description |
+|---------|-------------|
+| `totem create` | Create a new memory item |
+| `totem get <ID>` | Retrieve by ID (`--no-evidence` skips staleness check) |
+| `totem update <ID>` | Update an item (`--reason` optional, defaults to "maintenance") |
+| `totem delete <ID>` | Soft-delete (requires `--reason`) |
+| `totem list` | List with `--sort` (`created_at`, `updated_at`, `importance`) and filters |
+| `totem recent` | List most recently created memories (`--limit` default 5) |
+| `totem resolve <ID>` | Mark a conflict as resolved (`--resolution` required) |
+| `totem search` | Full-text search (includes tags) with type/tag filters |
+| `totem export` | Export all memories and conflicts as JSON (`-o` for file output) |
+| `totem import <FILE>` | Import memories from a JSON export file |
+| `totem context` | Assemble scored context for a task |
+
+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:
+
+| Type | Purpose | Metadata |
+|------|---------|----------|
+| `decision` | A choice that was made | `rationale` (optional, but strongly recommended: explain WHY) |
+| `invariant` | A rule that must hold | `verificationMethod`, `condition` (required) |
+| `gotcha` | A non-obvious pitfall discovered | (none) |
+| `rejected_idea` | A proposal that was considered and declined | `proposal`, `reasonRejected` (required) |
+
+## 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:
+
+```bash
+# 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`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Auto-generated primary key |
+| `type` | enum | `decision`, `invariant`, `gotcha`, `rejected_idea` |
+| `title` | str | Short title |
+| `statement` | str | The factual claim |
+| `details` | str? | Additional context |
+| `tags` | list[str] | At least one required |
+| `status` | enum | `active`, `potentially_stale`, `invalidated`, `deleted` |
+| `confidence` | float | 0 to 1, default 1.0 |
+| `importance` | float | 0 to 1, default 0.5 |
+| `evidence` | list[Evidence] | Linked source code with content hashes |
+| `metadata` | dict? | Type-specific keys (see memory types above) |
+
+Evidence entries link to source code ranges with SHA256 hashes for staleness detection.
+
+## Companion skill
+
+The [`skills/precision-first/`](skills/precision-first/SKILL.md) 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
+
+```bash
+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

totem_mcp-0.1.0/README.md

@@ -0,0 +1,302 @@
+# totem
+
+<p align="center">
+  <a href="https://pypi.org/project/totem-mcp/">
+    <img src="https://img.shields.io/pypi/v/totem-mcp?logo=pypi&logoColor=white&style=for-the-badge" alt="PyPI">
+  </a>
+  <a href="https://pypi.org/project/totem-mcp/">
+    <img src="https://img.shields.io/pypi/pyversions/totem-mcp?logo=python&logoColor=white&style=for-the-badge" alt="Python">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-10AC84?style=for-the-badge" alt="License">
+  </a>
+  <a href="https://modelcontextprotocol.io">
+    <img src="https://img.shields.io/badge/MCP-Compatible-8A2BE2?logo=modelcontextprotocol&logoColor=white&style=for-the-badge" alt="MCP">
+  </a>
+
+</p>
+
+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+.
+
+```bash
+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:**
+```bash
+claude mcp add totem -- uvx totem-mcp
+```
+
+**opencode** (add to `~/.config/opencode/opencode.json`):
+```json
+{
+  "mcp": {
+    "totem": {
+      "type": "local",
+      "command": ["uvx", "totem-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+**Claude Desktop / Cursor / Windsurf** (add to config):
+```json
+{
+  "mcpServers": {
+    "totem": {
+      "command": "uvx",
+      "args": ["totem-mcp"]
+    }
+  }
+}
+```
+
+**VS Code** (add to `.vscode/mcp.json`):
+```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:
+
+```bash
+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
+
+```bash
+# 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.
+
+| Tool | Description |
+|------|-------------|
+| `memory_create_tool` | Create a memory item. Provide `rationale` in metadata for decisions (strongly recommended). |
+| `memory_get_tool` | Retrieve by ID with staleness check |
+| `memory_update_tool` | Update any field. Provide `reason` (strongly recommended for audit trail). |
+| `memory_delete_tool` | Soft-delete (requires `reason`) |
+| `memory_list_tool` | Filtered listing with `sort` param (`created_at`, `updated_at`, `importance`) |
+| `memory_recent_tool` | List most recently created memories (default limit 5) |
+| `memory_search_tool` | FTS5 full-text search (includes tags) with type/tag filters |
+| `resolve_conflict_tool` | Mark a conflict as resolved with a resolution description |
+| `engineering_context_tool` | Scored context assembly; searches project + user DBs |
+| `memory_export_tool` | Export all memories and conflicts as portable JSON |
+| `memory_import_tool` | Import memories from an export dict (skips duplicate IDs) |
+
+## CLI commands
+
+All commands accept `--project <path>` to override workspace scoping.
+
+| Command | Description |
+|---------|-------------|
+| `totem create` | Create a new memory item |
+| `totem get <ID>` | Retrieve by ID (`--no-evidence` skips staleness check) |
+| `totem update <ID>` | Update an item (`--reason` optional, defaults to "maintenance") |
+| `totem delete <ID>` | Soft-delete (requires `--reason`) |
+| `totem list` | List with `--sort` (`created_at`, `updated_at`, `importance`) and filters |
+| `totem recent` | List most recently created memories (`--limit` default 5) |
+| `totem resolve <ID>` | Mark a conflict as resolved (`--resolution` required) |
+| `totem search` | Full-text search (includes tags) with type/tag filters |
+| `totem export` | Export all memories and conflicts as JSON (`-o` for file output) |
+| `totem import <FILE>` | Import memories from a JSON export file |
+| `totem context` | Assemble scored context for a task |
+
+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:
+
+| Type | Purpose | Metadata |
+|------|---------|----------|
+| `decision` | A choice that was made | `rationale` (optional, but strongly recommended: explain WHY) |
+| `invariant` | A rule that must hold | `verificationMethod`, `condition` (required) |
+| `gotcha` | A non-obvious pitfall discovered | (none) |
+| `rejected_idea` | A proposal that was considered and declined | `proposal`, `reasonRejected` (required) |
+
+## 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:
+
+```bash
+# 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`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Auto-generated primary key |
+| `type` | enum | `decision`, `invariant`, `gotcha`, `rejected_idea` |
+| `title` | str | Short title |
+| `statement` | str | The factual claim |
+| `details` | str? | Additional context |
+| `tags` | list[str] | At least one required |
+| `status` | enum | `active`, `potentially_stale`, `invalidated`, `deleted` |
+| `confidence` | float | 0 to 1, default 1.0 |
+| `importance` | float | 0 to 1, default 0.5 |
+| `evidence` | list[Evidence] | Linked source code with content hashes |
+| `metadata` | dict? | Type-specific keys (see memory types above) |
+
+Evidence entries link to source code ranges with SHA256 hashes for staleness detection.
+
+## Companion skill
+
+The [`skills/precision-first/`](skills/precision-first/SKILL.md) 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
+
+```bash
+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

totem_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "totem-mcp"
+version = "0.1.0"
+description = "Persistent memory layer for engineering agents"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "pydantic>=2.0,<3.0",
+    "click>=8.0,<9.0",
+    "mcp>=1.0,<2.0",
+    "pyturso>=0.7.2",
+]
+
+[[project.authors]]
+name = "Emiliano Gandini Outeda"
+email = "emiliano.gandini@protonmail.com"
+
+[project.scripts]
+totem = "totem_mcp.cli:main"
+totem-mcp = "totem_mcp.cli:mcp_main"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"

totem_mcp-0.1.0/pyproject.toml.orig

@@ -0,0 +1,23 @@
+[project]
+name = "totem-mcp"
+version = "0.1.0"
+description = "Persistent memory layer for engineering agents"
+readme = "README.md"
+authors = [
+    { name = "Emiliano Gandini Outeda", email = "emiliano.gandini@protonmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "pydantic>=2.0,<3.0",
+    "click>=8.0,<9.0",
+    "mcp>=1.0,<2.0",
+    "pyturso>=0.7.2",
+]
+
+[project.scripts]
+totem = "totem_mcp.cli:main"
+totem-mcp = "totem_mcp.cli:mcp_main"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"

totem_mcp-0.1.0/src/totem_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""totem: persistent memory for engineering agents."""
+
+__version__ = "0.1.0"

totem_mcp-0.1.0/src/totem_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+main()