terminal Documentation for a project you run yourself

Tropelex Documentation

This page describes what Tropelex does once installed — it isn't a live instance. See the README or Getting Started to run it against your own project.

AI Memory System with Safety and Alignment Infrastructure. Store decisions, track patterns, and maintain project context across sessions. The same mechanisms double as auditable safety infrastructure — see SAFETY.md for how.

rocket_launch

Getting Started

System prerequisites, server initialization & client integration

bolt Quickstart

download 1. System Prerequisites & Installation

Tropelex requires Python 3.10+. Clone the repository and install core dependencies:

git clone https://github.com/kylosarc/tropelex.git
cd tropelex
pip install -r requirements.txt

dns 2. Launch the Tropelex Server

Start the REST API backend server from the repository root (runs by default at http://localhost:8766):

python3 -m core.tropebook.web.server

All client interfaces (Dashboard, MCP server, VSCode Extension, Emacs, TUI, OpenCode, Devin, Cursor, Aider) communicate with this backend server.

create_new_folder 3. Create a Project Container

Projects are the top-level container for all memory. Open the web dashboard at http://localhost:8766, go to Memory in the sidebar, and click New Project.

post_add 4. Record Decisions & End Sessions

Decisions are the core building block of Tropelex memory. Click + Add Decision in the Memory section to record architectural rationale:

Decision text — what you decided (e.g., "Using Python + FastAPI for backend")
Context — why you decided it (optional but recommended; editable via PATCH /api/memory/{project}/decisions/{id}/context)

When completing a work session, click + End Session to summarize work done and update pattern tracking.

key 5. Configure API Keys (Optional)

Set optional environment variables in your shell or .env file to enable advanced AI and search features:

BRAVE_SEARCH_API_KEY — Primary provider for citation-grade Deep Research and web search features.
EXA_API_KEY / SERPER_API_KEY — Cost-effective/free alternatives to Brave. Auto-Research (/api/research/auto) tries Brave → Exa → Serper → DuckDuckGo.
OPENAI_API_KEY — Enables text-embedding-3-small embeddings and gpt-4o-mini LLM compression/refinement. Dict/concatenation fallbacks run automatically if key is absent.

devices 6. Pick Your Client Interface

Tropelex provides 6 integrated ways to interact with project memory:

dashboard

Web DashboardVisual browser management at 8766

api

MCP Server & PromptsClaude Code, Cursor, Devin, Zed

code

VSCode ExtensionSidebar viewer & Memory Lens annotations

terminal

Terminal UI & OpenCodeTextual dashboard & slash commands

alt_route

Recommended AI Agent Coding Loop

4-phase autonomous agent lifecycle for drift prevention

loop Lifecycle

When an AI agent operates within a project using Tropelex, it follows a 4-phase lifecycle to maintain architectural consistency and prevent silent drift:

flag Phase	Agent Goal	Tropelex Tool / Endpoint	Description
play_circle 1. Init	Prefetch minimal relevant context	`get_context_bundle` / `GET /api/memory/{project}/context`	Predicts and bundles active decisions, patterns, and tech stack within a token budget before coding starts.
security 2. Pre-Write	Prevent code drift & contradictions	`check_diff_for_conflicts` / `POST /api/memory/{project}/ghost-check`	Evaluates proposed code diffs against recorded decisions. Returns severity warnings prior to file mutation.
save 3. Rationale	Record new architectural choices	`capture_decision` / `POST /api/memory/{project}/decisions`	Stores new technical decisions with rationale, superseding older choices or surfacing unresolved contradictions.
task_alt 4. Completion	Persist session summary & proficiency	`end_session` & `record_skill_outcome`	Summarizes session outcomes, logs friction signals, updates per-agent safety budgets, and updates calibration stats.

memory

1. Engine Core

Central memory state, graph relations & prompt preprocessing

space_dashboard Overview

Landing overview: quick stats, recent activity timeline, and Getting Started onboarding progress. (UI Tab: Overview)

database Memory

View and manage project memory — decisions, session logs, developer preferences, and active patterns. Supports decision context backfilling (PATCH /api/memory/{project}/decisions/{id}/context) and soft-deleting projects (DELETE /api/memory/{project}) with 30-day trash retention. (UI Tab: Memory / MCP get_project_memory / API GET /api/memory/{project})

track_changes Goals

Goal entity tracking, inline goal editing (text/priority/category), goal-shaped language detection (detect_goals), adherence scoring, and continuous context re-anchoring. (UI Tab: Goals / API GET /api/memory/{project}/goals)

hub Patterns

Auto-detected architectural and workflow patterns learned from recorded sessions and git activity. (UI Tab: Patterns / API GET /api/patterns)

account_tree Knowledge Graph

Visual D3 force-directed graph rendering relationships between decisions (supersedes, caused_by, related_to). (UI Tab: Knowledge Graph)

science Prompt Lab

3-stage prompt preprocessor: compression, context gap checking, and imperative output structuring (TASK / CONSTRAINTS / CONTEXT). (UI Tab: Prompt Lab / API /prompt-lab)

high_quality

2. Quality & Integrity

Confidence scoring, ghost drift detection, pre-write checks & friction mining

analytics Insights

Decision intelligence: confidence scoring, agent proficiency tracking, decision timeline chains, ADR generation, session replay, and cross-project knowledge transfer. (UI Tab: Insights / API GET /api/memory/{project}/insights)

health_metrics Health

Aggregate project health score based on decision confidence tiers, session coverage, and pattern stability. (UI Tab: Health / API GET /api/health)

trending_up Impact

Calculates downstream decision dependency graphs, identifying high-impact choices, reversal rates, and ROI scoring. (UI Tab: Impact / API GET /api/memory/{project}/decision-impact)

visibility_off Ghost Decisions

Detects silent code drift by scanning git diffs and code keywords against documented decision constraints. (UI Tab: Ghost Decisions / MCP check_diff_for_conflicts / API POST /api/memory/{project}/ghost-check)

gavel Pre-Write Guard

Prevents bad edits before writing code. Checks a proposed git diff against active decisions and returns severity-scored compliance alerts. (UI Tab: Pre-Write Guard / MCP check_diff_for_conflicts / API POST /api/memory/{project}/ghost-check)

record_voice_over Friction Mining

Scans conversation transcripts for frustration markers (rephrasing, retry loops, escalation phrases) to capture implicit preferences. (UI Tab: Friction Mining / MCP friction_scan / API POST /api/friction/scan / Emacs C-c t f)

compare_arrows Contradictions

Scans for opposing decision pairs ("use REST" vs "use GraphQL") and surfaces active conflict warnings with resolution suggestions. (UI Tab: Contradictions / MCP check_contradictions / API GET /api/memory/{project}/contradictions)

show_chart Session Shape

Baselining tool-call frequency, token budgets, and latency drift signals per agent. Correlates session-shape deviations against subsequent Ghost overrides or elevated friction scans, reported as lift over the baseline rate. (UI Tab: Session Shape / API GET /api/memory/{project}/agents/{agent}/session-shape, .../session-shape/correlation)

psychology

3. Explainability & Discovery

Causal architectural Q&A, context prefetch, doc mining & decision lineage

forum Why Do We...? Chat

Ask natural language questions about architectural decisions. Fuses RAG + decision tree + impact analysis into causal answers. (UI Tab: Why Do We...? / MCP explain_why / API POST /api/explain)

cloud_download Context Prefetch

Predicts the optimal minimal context bundle for a task, sized to a token budget and prioritized by decision impact score. (UI Tab: Context Prefetch / MCP get_context_bundle / API GET /api/memory/{project}/prefetch)

find_in_page Doc Mining

Scans repository markdown files for doc-vs-decision contradictions, doc-vs-doc drift, and uncaptured decision statements: (UI Tab: Doc Mining / API POST /api/memory/{project}/docmine/scan)

curl -X POST http://localhost:8766/api/memory/<project>/docmine/scan -d '{"paths": ["README.md", "docs/"]}'

timeline Decision Lineage

Visual tree showing decision evolution, version history, and parent-child parentage chains across project iterations. (UI Tab: Decision Lineage / API GET /api/memory/{project}/decisions/{id}/versions)

shield_lock

4. Safety & Alignment

Risk classification, governance review workflow & compliance framework

Risk classification, review workflow, and compliance framing for the decision graph — backed by auditable safety mechanisms. See SAFETY.md for full specifications.

verified_user Safety Infrastructure Highlights

account_balance_wallet
Per-Agent Safety BudgetWeighted running total tracking gate blocks, warnings, and high-risk decisions per agent, auto-escalating that agent's most recent decision for review once over threshold. (GET /api/memory/{project}/agents/{agent}/safety-budget, POST .../safety-budget/escalate)
schedule
Knowledge DecayDecision confidence scores decay automatically over time (default 90-day half-life).
shield
Prompt Injection DefenseContext compression normalizes prompts, shrinking instruction injection surfaces.
policy
Compliance GatesAutomated checks enforcing EU AI Act, NIST, and ISO 42001 governance policies.

dashboard Dashboard

Risk trends, aggregate exposure metrics, and security scoring across project memory. (UI Tab: Dashboard / API GET /api/memory/{project}/safety-dashboard)

tune Alignment

Evaluates interpretability, safety, fairness, robustness, and governance drift between evaluation runs. (UI Tab: Alignment / API GET /api/memory/{project}/alignment/evaluate)

gavel Governance

Compliance checks against EU AI Act, NIST, and ISO 42001 frameworks with automated governance report generation. (UI Tab: Governance / API GET /api/memory/{project}/governance/compliance)

fingerprint Provenance & Integrity

Immutable provenance chain verification, signature checks, tamper detection, and security audit logging for all decisions. (UI Tab: Provenance / API GET /api/memory/{project}/provenance/chain)

rate_review Reviews

Human-in-the-loop review queue for decisions tagged requires_review, offering mitigation advice and audit tracking. (UI Tab: Reviews / API GET /api/memory/{project}/reviews/pending)

dataset Synthetic Data Policy

EU AI Act Art. 10 & 50 registration for synthetic datasets — privacy budget tracking, bias audits, and compliance gate enforcement. (UI Tab: Synthetic Data / API GET /api/memory/{project}/synthetic-data/summary)

bug_report Agent Surface Audit

Audits the agent's harness config (CLAUDE.md, AGENTS.md, .mcp.json, hooks, skills) for hardcoded secrets, broad permissions, and injection risks (Grades A–F): (UI Tab: Agent Audit / API POST /api/agent-audit/scan)

curl -X POST http://localhost:8766/api/agent-audit/scan?repo_path=/path/to/repo

speed Drift-Bench

Continuous safety regression suite evaluating alignment drift and goal stability across multi-turn agent sessions. (UI Tab: Drift-Bench / API GET /api/memory/{project}/alignment/drift)

history_toggle_off

5. Memory Lifecycle

Time travel postmortem debugging & epoch compaction

history Time Travel

Inspect project memory state as of any past date. Forensic postmortem debugger tool. (UI Tab: Time Travel / API GET /api/memory/{project}/timetravel)

compress Memory Compaction

Collapses long, superseded decision chains into epoch summaries to maintain token efficiency. (UI Tab: Compaction / API POST /api/memory/{project}/compact)

science

6. Research & Ingestion

Deep research, shared feeds, decision promotion & citation stores

rss_feed Research Feeds

Scheduled research feeds, optionally scoped to one project or shared across several (POST /api/research-feeds/{feed_id}/share), with automatic interval adjustment on novelty/anomaly signals and on-demand LLM query-rewrite suggestions for stagnant feeds (POST /api/research-feeds/{feed_id}/suggest-query-rewrite), plus citation health metrics and bulk config export/import. (UI Tab: Research Feeds / API GET /api/research-feeds / MCP list_research_feeds)

manage_search Deep Research

Dual-engine research system (Multi-Source Scan + Citation-Grade Web Research) with a quick/thorough budget preset (wall-time and step-count, not token/source caps — the underlying engines don't expose those), query-fingerprint caching for repeat queries, and one-click Decision Promotion (POST /api/memory/{project}/research/promote-candidates) with deterministic citation-diversity confidence scoring. A "Research this decision's rationale" action on any decision card seeds a fresh research run from that decision's own text and attaches results back via PATCH /api/memory/{project}/decisions/{id}/citation-ids. (UI Tab: Deep Research / API POST /api/memory/{project}/deep-research/web-research / MCP run_deep_research)

donut_large Source Coverage

Per-project breakdown of which sources (by domain — GitHub, Reddit, academic, etc.) are actually producing citations a decision has cited, vs. noise, with a per-project suppression list for low-value sources. (API GET /api/memory/{project}/research/source-coverage, GET/PUT /api/memory/{project}/research/disabled-sources)

library_books Tropebook

Citation library and research knowledge base for storing reference URLs, managing tags, and monitoring flagged citations in Needs Attention. (UI Tab: Tropebook / API GET /api/citations / CLI tropelex)

find_in_page Repo Seek

Automated repository scanner that parses source code for uncaptured citations, external links, and reference docs with Add/Exclude controls and one-click Deep Research scanning. (UI Tab: Repo Seek / API POST /api/reposeek/scan)

Analyzes topic velocity, emerging technical keywords, and trend signals across research runs, source coverage dashboards, and scheduled feeds. (UI Tab: Trending / API GET /api/trending)

groups

7. Team & Collaboration

Agent handoffs, PR bot delivery, narrative generation & Slack capture

swap_calls Agent Handoff

Generates role-aware, token-budgeted context packets for inter-agent delegation. (UI Tab: Agent Handoff / MCP get_handoff_packet / API POST /api/handoff/build)

merge_type PR Bot

Generates pull request comments containing relevant decision context and ghost warnings. (UI Tab: PR Bot / API POST /api/prbot/comment)

auto_stories Narrative Mode

Converts decision graphs into human-readable prose with audience presets (new hire, investor, PM). (UI Tab: Narrative / API GET /api/narrative/{project})

query_stats Decision Market

Place confidence bets on decisions to track calibration and accuracy over time. (UI Tab: Decision Market / API POST /api/market/bet)

chat Slack Capture

Extracts decisions and implicit architectural rationale directly from Slack chat threads. (UI Tab: Slack Capture / API POST /api/slack/events)

badge Personas

Synthesizes readable behavioral personas from agent proficiency metrics. (UI Tab: Personas / API GET /api/personas/{agent})

hub

8. Integrations & Ops

Git sync, cross-project benchmarks & financial cost ledgers

commit Git Integration

Tech stack detection, conventional commit decision extraction, and deep diff parsing for rationale and revert chains. (UI Tab: Git / API POST /api/sync/git)

bar_chart Benchmarks

Privacy-preserving cross-project decision metrics and reversal rate comparisons. Supports offline JSON import/export. (UI Tab: Benchmarks / API GET /api/benchmarks)

payments Cost Ledger

Tracks actual financial dollars and LLM tokens spent per decision to measure ROI. (UI Tab: Cost Ledger / API GET /api/cost/{project})

new_releases Versioning

Two independently-tracked version numbers: the app version (shown in the dashboard footer and GET /api/health) and a memory schema version that only bumps when the on-disk/export JSON shape changes in a way that could break cross-install compatibility. Check both are on the same app version before moving data between machines — POST /api/account/import 409s on a schema mismatch (or a missing schema_version, from an export predating this field) unless you explicitly confirm, and a mismatched Benchmarks bundle surfaces a real warning instead of an unexplained skip count. See the README's Versioning section for the full policy.

api

MCP Server & Prompts Integration

Model Context Protocol tools & prompts for AI coding assistants

Everything in Tropelex is exposed via the Model Context Protocol (MCP), enabling agents in Claude Code, Cursor, Claude Desktop, Devin, Gemini CLI, and Zed to interact directly with project memory. The server code lives in mcp_server/.

Quick Setup

cd mcp_server
uv venv .venv
uv pip install --python .venv/bin/python -r requirements.txt

Automatic Registration (Claude Code)

A repository-scoped .mcp.json is pre-configured at the repo root. Opening Tropelex in Claude Code registers the MCP server automatically via mcp_server/run.sh.

Manual Registration

claude mcp add tropelex -- /path/to/Tropelex/mcp_server/.venv/bin/python /path/to/Tropelex/mcp_server/server.py

handyman Available MCP Tools

Tool Name	Parameters	Description
`list_projects`	None	List all recorded project memory containers.
`get_project_memory`	`project`	Retrieve active decisions, patterns, and preferences for a project.
`capture_decision`	`project`, `decision`, `context`, `risk_level`	Store a new architectural decision.
`propose_goal`	`project`, `text`, `priority`, `category`	Propose a prospective goal for a project (the counterpart to decisions).
`end_session`	`project`, `summary`, `agent`	Summarize session and trigger pattern detection. Pass `agent` handle.
`get_context_bundle`	`project`, `task`, `token_budget`	Fetch optimal prefiltered context bundle for a task.
`check_contradictions`	`project`	Scan project memory for conflicting decisions.
`check_diff_for_conflicts`	`project`, `diff`	Pre-write check: evaluate git diff against active decisions.
`override_ghost_warning`	`project`, `decision_id`, `rationale`, `agent`	Explicitly accept a blocked ghost/contradiction warning on one decision.
`friction_scan`	`project`, `transcript`, `agent`	Scan conversation transcript for user frustration signals.
`record_skill_outcome`	`project`, `session_type`, `categories`, `outcome`, `agent`	Record outcome for agent calibration & persona tracking.
`get_handoff_packet`	`project`, `role`, `token_budget`, `agent`	Build role-aware context packet for agent handoffs.
`acknowledge_handoff`	`project`, `packet_hash`, `agent`, `acknowledged_constraints`	Acknowledge receipt of a handoff packet, recorded to the audit trail.
`explain_why`	`project`, `question`	Ask natural language causal questions about decisions.
`run_deep_research`	`project`, `query`, `hybrid`, `max_steps`	Run Deep Research (citation-grade web research, optionally hybrid with the multi-source engine).
`list_research_feeds`	None	List all configured research feeds.
`get_research_feed`	`feed_id`	Retrieve details and recent run results for a research feed.
`run_research_feed`	`feed_id`	Trigger an immediate execution of a research feed.

terminal MCP Prompts (Slash Command Parity)

Exposes 4 MCP prompts (defined in mcp_server/server.py) enabling auto-generated slash commands in Devin, Gemini CLI, and Zed — named after their Python function, so the generated command carries the tropelex_ prefix:

tropelex_show_context — Retrieves accumulated project context bundle
tropelex_record_decision — Prompts for decision title and rationale context
tropelex_end_session — Prompts for session summary
tropelex_up — Initializes or updates project description and tech stack

grid_view AI Tool Support Matrix

Claude Code / OpenCode: .mcp.json + plugins/tropelex.js plugin
Cursor & Codex CLI: Shared Agent Skills standard deployed to .agents/skills/ and .cursor/skills/
Devin, Gemini CLI, Zed: Automatic slash command generation via MCP Prompts
Aider: Shell script integration invoked via /run tropelex-record-decision

code

VSCode Extension Integration

Sidebar memory viewer & Memory Lens inline annotations

The Tropelex VSCode extension (vscode-tropelex/) provides native sidebar memory management and inline editor decision scanning (Memory Lens).

Installation

Open vscode-tropelex/ in VSCode and press F5 to launch in extension development mode, or package it using vsce package and install the resulting .vsix.

Configuration Settings

Setting	Default	Description
`tropelex.serverUrl`	`http://localhost:8766`	URL of the running Tropelex backend server.
`tropelex.project`	Workspace folder name	Tropelex project target name. Auto-detected if empty.
`tropelex.instanceSecret`	`""`	Required `TROPEL_EX_SECRET` value when server instance authentication is enabled.

Contributed Commands & Views

Project Memory View: Dedicated Activity Bar icon ($(brain)) providing an interactive list of active decisions.
Editor Context Menu: Right-click focus in any editor buffer and select Scan File for Decision References (Memory Lens) (tropelex.scanFileForDecisions) to view inline annotations linking code to decisions.
tropelex.openMemoryViewer — Opens the primary memory sidebar view.
tropelex.refreshMemory — Force-refreshes project decisions and session context.
tropelex.clearLensAnnotations — Clears inline Memory Lens editor decorations.

terminal

Terminal UI (TUI)

Textual terminal dashboard for tmux users

A Textual-based terminal dashboard in tui/ for tmux users. Browse projects, inspect decisions, and record new rationale without leaving the terminal.

cd tui
uv venv .venv
uv pip install --python .venv/bin/python -r requirements.txt
.venv/bin/python app.py

Keybindings

a — Add new decision modal
r — Refresh decision list
q — Quit TUI

terminal

AI Coding Tools & Slash Commands

Native slash command parity across OpenCode, Claude Code, Devin, Gemini CLI, Zed, Cursor & Aider

Tropelex exposes unified slash commands across all major AI coding environments. Commands are delivered via OpenCode plugins, MCP prompts, Agent Skills, or shell scripts.

terminal Slash Commands Matrix

Slash Command	Supported AI Tools	Usage & Description
`/tropelex-record-decision` or `/tropelex_record_decision`	OpenCode, Claude Code, Devin, Gemini CLI, Zed, Cursor, Aider	Record architectural choice: `/tropelex-record-decision Using PostgreSQL for database`
`/tropelex-end-session` or `/tropelex_end_session`	OpenCode, Claude Code, Devin, Gemini CLI, Zed, Cursor, Aider	Summarize work session: `/tropelex-end-session Built user auth with JWT`
`/tropelex-show-context` or `/tropelex_show_context`	OpenCode, Claude Code, Devin, Gemini CLI, Zed, Cursor, Aider	Display optimal context bundle for active task
`/tropelex-up` or `/tropelex_up`	OpenCode, Claude Code, Devin, Gemini CLI, Zed	Initialize or update project description and tech stack

build Tool-by-Tool Integration Guide

terminal OpenCode Plugin

Defined in .opencode/ and plugins/tropelex.js. Copy to your OpenCode plugins directory:

cp plugins/tropelex.js ~/.config/opencode/plugins/tropelex.js

Add "tropelex" to the "plugin" array in ~/.config/opencode/opencode.json.

api Claude Code

Auto-configured via root .mcp.json. Provides native slash commands /tropelex-up, /tropelex-record-decision, /tropelex-end-session, and /tropelex-show-context.

smart_toy Devin, Gemini CLI & Zed

Zero-config slash command parity via MCP Prompts in mcp_server/server.py — these tools auto-generate slash commands /tropelex_show_context, /tropelex_record_decision, /tropelex_end_session, and /tropelex_up automatically upon connection.

code Cursor & Codex CLI

Powered by the open Agent Skills standard. Deployed to .agents/skills/ and .cursor/skills/ for automatic prompt context inclusion.

terminal Aider Integration

Invoked directly via Aider's built-in /run command executing local shell scripts: /run tropelex-record-decision.

edit_note

Emacs Integration

Zero-dependency elisp package for instant capture

Zero-dependency Emacs package (emacs/tropelex-capture.el) for capturing decisions and friction signals straight from your editor.

Setup

(add-to-list 'load-path "~/Tropelex/emacs")
(require 'tropelex-capture)
(tropelex-capture-mode 1)

Keybindings

C-c t c — Capture decision with auto-detected buffer context (file, mode, function)
C-c t r — Capture active region (code snippet, log trace) as decision context
C-c t f — Scan buffer for friction patterns
C-c t g — Capture current HEAD git commit message as decision
C-c t s — Check server connectivity and current project
C-c t p — Override active project name for session

terminal

CLI Reference

Command-line interface for the Tropebook citation engine

Local command-line interface for the Tropebook citation engine (core/tropebook/cli.py), installed via pyproject.toml.

Command	Description
`tropelex add <title> <url> [summary]`	Add reference citation
`tropelex search <query>`	Search knowledge base
`tropelex list [tag]`	List citations with optional tag filter
`tropelex import <file>`	Import citations from JSON/markdown file
`tropelex stats`	Display citation library stats
`tropelex link <url1> <url2> <rel>`	Link two citations with a relationship

Direct module fallback: python -m core.tropebook.cli <command>.

http

API Reference

REST API endpoint examples for all memory & safety modules

All features expose REST API endpoints on http://localhost:8766. Once you're running it yourself, view interactive OpenAPI documentation at localhost:8766/openapi.json.

POST 1. Record Decision

curl -X POST http://localhost:8766/api/memory/my_project/decisions \
  -H "Content-Type: application/json" \
  -d '{"decision": "Using FastAPI", "context": "Requires high performance async endpoints"}'

PATCH 2. Backfill Decision Context

curl -X PATCH http://localhost:8766/api/memory/my_project/decisions/dec_123/context \
  -H "Content-Type: application/json" \
  -d '{"context": "Updated context rationale after review"}'

POST 3. Promote Candidate Decision from Research

curl -X POST http://localhost:8766/api/memory/my_project/decisions/promote \
  -H "Content-Type: application/json" \
  -d '{"decision": "Adopt vector search", "context": "Recall was the bottleneck", "citation_ids": ["cit_456"], "safety_metadata": {"safety_category": "general"}}'

POST 4. Pre-Write Diff Guard (Ghost Check)

curl -X POST http://localhost:8766/api/memory/my_project/ghost-check \
  -H "Content-Type: application/json" \
  -d '{"diff": "--- a/db.py\n+++ b/db.py\n+import sqlite3"}'

DELETE 5. Soft-Delete Project

curl -X DELETE http://localhost:8766/api/memory/my_project

tune

Environment Variables Reference

Configuration flags for server, clients, research backends & OpenAI

Variable	Scope	Default	Description
`TROPELEX_URL`	Clients	`http://localhost:8766`	Server base endpoint for MCP, VSCode, Emacs, OpenCode, and TUI.
`TROPELEX_PROJECT`	Clients	Workspace directory name	Overrides target project name across integrations.
`TROPEL_EX_SECRET`	Server / Auth	None	Instance authentication token required when server auth is enabled.
`OPENAI_API_KEY`	AI Services	None (Fallback active)	Enables `text-embedding-3-small` and `gpt-4o-mini` compression/refinement.
`BRAVE_SEARCH_API_KEY`	Deep Research	None	Primary key for Brave search provider.
`EXA_API_KEY` / `SERPER_API_KEY`	Deep Research	None	Fallback keys for Exa/Serper web research providers.
`TROPELEX_COMPRESS_MIN`	OpenCode	`80`	Prompt length threshold for automatic prompt compression.
`TROPELEX_INJECT_CONTEXT`	OpenCode	`true`	Automatically injects project context into new prompt sessions.

account_tree

Architecture & Storage Layout

Zero external database dependencies & local file persistence

Tropelex is designed with clean architectural boundaries and zero database external dependencies:

layers Core Technical Stack

FastAPI: High-performance async REST API server.
JSON File Engine + fcntl.flock: Thread-safe and process-safe local persistence with lockfile synchronization.
Soft-Delete Trash Retention: memory/.trash/YYYY-MM-DD/ directory holding deleted project memory with 30-day retention.
D3.js: Interactive browser-side force-directed knowledge graph.
Pure Business Logic: Side-effect-free functional decision calculations.

folder_open On-Disk Storage Layout

All project data is stored under the local memory/ directory. Each project is one flat JSON file, not a directory of separate files:

memory/
├── <project_name>.json  # One file per project: decisions, goals,
│                        # session_history, patterns, audit_log, safety
│                        # and alignment state -- all as keys in a single
│                        # document, not split across separate files
├── .trash/
│   └── YYYY-MM-DD/      # Soft-deleted projects, 30-day retention
├── tropebook/           # Citation library -- a single store shared
│                        # across every project, not nested per-project
└── feeds/               # Research feed configs & run history, global
                          # by default with optional per-project scope

help

Troubleshooting

Common operational diagnostics & solutions

refresh A Panel Shows Empty, Zero, or Unexpectedly Stale Data

Try a hard refresh (Ctrl+Shift+R on Windows/Linux, Cmd+Shift+R on Mac) before assuming something is broken. If the dashboard server was restarted while your browser tab was already open, a normal refresh can still serve stale page state — this is the single most common cause of "no data" symptoms and is worth trying first, every time, even if it seems unlikely to help.

warning "Cannot reach Tropelex" / Connection Refused

The server is not running. Launch it from the repository root:

python3 -m core.tropebook.web.server

extension_off MCP Server or TUI Fails with `ModuleNotFoundError`

Both tools run in isolated venvs. Set up dependencies in their respective directories:

uv venv .venv
uv pip install --python .venv/bin/python -r requirements.txt

link_off VSCode Extension Fails to Connect

Verify that tropelex.serverUrl matches your running server URL. If server instance auth is enabled, ensure tropelex.instanceSecret contains the matching TROPEL_EX_SECRET key.

search_off OpenCode Commands Missing from Palette

Ensure plugins/tropelex.js is copied to ~/.config/opencode/plugins/ and registered in opencode.json under the "plugin" array.

Tropelex Documentation

Getting Started

download 1. System Prerequisites & Installation

dns 2. Launch the Tropelex Server

create_new_folder 3. Create a Project Container

post_add 4. Record Decisions & End Sessions

key 5. Configure API Keys (Optional)

devices 6. Pick Your Client Interface

Recommended AI Agent Coding Loop

1. Engine Core

space_dashboard Overview

database Memory

track_changes Goals

hub Patterns

account_tree Knowledge Graph

science Prompt Lab

2. Quality & Integrity

analytics Insights

health_metrics Health

trending_up Impact

visibility_off Ghost Decisions

gavel Pre-Write Guard

record_voice_over Friction Mining

compare_arrows Contradictions

show_chart Session Shape

3. Explainability & Discovery

forum Why Do We...? Chat

cloud_download Context Prefetch

find_in_page Doc Mining

timeline Decision Lineage

4. Safety & Alignment

dashboard Dashboard

tune Alignment

gavel Governance

fingerprint Provenance & Integrity

rate_review Reviews

dataset Synthetic Data Policy

bug_report Agent Surface Audit

speed Drift-Bench

5. Memory Lifecycle

history Time Travel

compress Memory Compaction

6. Research & Ingestion

rss_feed Research Feeds

manage_search Deep Research

donut_large Source Coverage

library_books Tropebook

find_in_page Repo Seek

trending_up Trending

7. Team & Collaboration

swap_calls Agent Handoff

merge_type PR Bot

auto_stories Narrative Mode

query_stats Decision Market

chat Slack Capture

badge Personas

8. Integrations & Ops

commit Git Integration

bar_chart Benchmarks

payments Cost Ledger

new_releases Versioning

MCP Server & Prompts Integration

Quick Setup

Automatic Registration (Claude Code)

Manual Registration

handyman Available MCP Tools

terminal MCP Prompts (Slash Command Parity)

grid_view AI Tool Support Matrix

VSCode Extension Integration

Installation

Configuration Settings

Contributed Commands & Views

Terminal UI (TUI)

Keybindings

AI Coding Tools & Slash Commands

terminal Slash Commands Matrix

build Tool-by-Tool Integration Guide

Emacs Integration

Setup

Keybindings

extension_off MCP Server or TUI Fails with `ModuleNotFoundError`