Tropelex FAQ

Without Tropelex, every new session requires re-explaining architectural choices, tech stack preferences, and safety boundaries. Tropelex acts as a long-term memory layer that automatically injects relevant project decisions, learned coding patterns, and rationale graphs directly into the AI prompt context, keeping human developers and AI agents perfectly aligned over months of active development.

Here is how the components relate:

• Tropelex (Core Memory Engine): The parent framework (core/) providing project state storage, living ADRs, decision DAGs, causal Q&A, safety envelopes, and multi-agent coordination.
• Tropebook (Citation & Research Engine): The research subsystem (core/tropebook/) responsible for deep web search, multi-provider query routing (Brave, Exa, Serper, DuckDuckGo), citation extraction, and research feed scheduling.
• Web Dashboard (UI/animated_tropebook_dashboard/code.html): The interactive web front-end served at http://localhost:8766 providing visual management for all memory groups, knowledge graphs, and safety audit logs.
• MCP Server (mcp_server/server.py): The Model Context Protocol bridge allowing external AI tools (Claude Code, Devin, Cursor, Zed, Gemini CLI) to read and write memory directly.

Tropelex operates on a 100% local-first architecture:

• Project Decisions & Governance: memory/<project-name>.json (stores decisions, sessions, safety metrics, and confidence decay parameters).
• Research & Citations: memory/tropebook/citations.json and memory/tropebook/research_feeds.json.
• Session Diff Snapshots: memory/snapshots/ (stores timestamped unified diffs for time-travel and rollback).
• Soft-Deleted Projects: memory/.trash/<project-name>.json (retained for 30 days before permanent deletion).
• Security Hash Chains: Integrated directly into each decision record in memory/<project-name>.json as SHA-256 tamper-evident checksums.

No governance metrics or project code files are ever transmitted to third-party cloud servers or external databases.

Key privacy guarantees:

• Zero Telemetry Collection: All analytics, friction scores, and audit logs are computed locally on your machine.
• Plaintext Version-Controllable Files: Memory files are standard JSON, allowing teams to check architectural memory directly into Git repositories alongside their code.
• Offline Operation: The entire memory engine, decision DAG, Living ADR generator, and BM25 search fallback operate with 100% functionality on air-gapped networks.

Key project lifecycle features:

1. Isolated Namespaces: Decisions, sessions, goals, and agent budgets in project Alpha cannot leak into or overwrite project Beta.
2. Soft-Delete Safety: When a project is deleted via the API (DELETE /api/memory/{project}), it is moved into memory/.trash/<project>.json rather than immediately unlinked from disk.
3. 30-Day Trash Retention: Deleted projects in .trash/ remain restorable for 30 days. Projects older than 30 days are automatically purged during periodic maintenance ticks.
4. Controlled Cross-Pollination: To intentionally share architectural patterns between projects, Tropelex uses the explicit Cross-Pollination endpoint (GET /api/memory/{project}/cross-pollinate), which searches other projects for matching embeddings without merging raw memory stores.

Concurrency mechanisms:

• Atomic Replacement: Changes to memory/<project>.json are written to a temporary staging file (memory/.tmp_<project>_<pid>.json) and flushed to disk before executing an atomic OS-level rename.
• Optimistic Concurrency & ETag Verification: API write endpoints verify prev_hash integrity; if two agents mutate the same project memory simultaneously, the second write detects a hash mismatch (HTTP 409) and safely merges using non-destructive DAG append rules.

• Operating System: Linux, macOS, or Windows (via WSL2 or native PowerShell).
• Python Runtime: Python 3.10, 3.11, or 3.12+.
• Memory Footprint: ~80 MB RAM baseline for the FastAPI backend and in-memory DAG index.
• Storage Requirement: <50 MB for core installation; memory JSON files consume ~50 KB per 100 recorded decisions.
• Dependencies: FastAPI, Uvicorn, Requests, NumPy, Pytest. (Zero required database servers).

Follow these quick diagnostic steps:

1. Hard refresh the page: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac). If the dashboard server was restarted while your tab was open, a normal refresh can still serve stale page state — a hard refresh forces a clean reload and resolves this the vast majority of the time.
2. Check Global Project Selection: Look at the top-right header dropdown. If it displays No project, click to select your active project (e.g., Tropelex).
3. Run Diagnostic Self-Test: Navigate to Getting Started (Help Hub) and click Re-test All Systems to verify FastAPI backend connection and Pytest status.
4. Verify File Memory: Confirm that memory/<project-name>.json exists in your workspace root. If empty, run /tropelex-show-context or record a starter decision.

To resolve:

1. Find the running process PID: ``bash pgrep -f "core.tropebook.web.server" ``
2. Terminate the existing process: ``bash kill -9 $(pgrep -f "core.tropebook.web.server") ``
3. Restart the server: ``bash python3 -m core.tropebook.web.server ``

• Web Deep Research (/api/research/auto): Requires BRAVE_SEARCH_API_KEY, EXA_API_KEY, or SERPER_API_KEY. (DuckDuckGo fallback runs if none are provided).
• Vector Embeddings (/api/semantic-search): Uses OPENAI_API_KEY. If absent, Tropelex automatically switches to the offline TF-IDF keyword similarity fallback.
• Set keys in your environment or workspace .env file:

  export BRAVE_SEARCH_API_KEY="your_brave_key"
  export OPENAI_API_KEY="your_openai_key"

Resolution steps:

1. Hard Refresh: Press Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac) to bypass stale browser cache.
2. Verify Active Project: Check the project dropdown in the top-right header and ensure the correct project is active.
3. Check Server WebSocket Telemetry: Ensure the backend server is running and transmitting telemetry events.

1. Verify Server is Running: Confirm http://127.0.0.1:8766/api/health returns {"status": "ok"}.
2. Verify Python Path in MCP Config: Ensure the command in .mcp.json points to the correct virtualenv or system python3 binary with Tropelex dependencies installed.
3. Test MCP Server Directly: ``bash python3 -m mcp_server.server `` The process should start in stdio mode without throwing ImportError or syntax errors.

1. Confirm Plugin Installation: Ensure plugins/tropelex.js is copied to your OpenCode plugins directory: ``bash cp plugins/tropelex.js ~/.config/opencode/plugins/tropelex.js ``
2. Check opencode.json: Confirm "tropelex" is listed in the "plugin" array inside ~/.config/opencode/opencode.json.
3. Restart OpenCode: Fully restart your OpenCode session to reload plugins.

1. Validate JSON Syntax: ``bash python3 -m json.tool memory/<project>.json > /dev/null ``
2. Restore from Snapshot: Check memory/snapshots/ for the most recent session backup.
3. Check Soft-Delete Trash: If the file was inadvertently deleted, check memory/.trash/<project>.json.
4. Repair Hashes: If the file is valid JSON but fails integrity checks, run the hash backfill endpoint: ``bash curl -X POST http://localhost:8766/api/memory/<project>/security/backfill-hashes ``

All unit tests must pass before declaring features or bug fixes complete. Note: Last30Days engine tests consume external API tokens and are excluded by default; to run them explicitly, run pytest -m last30days.

Common Triggers:

• Sending empty or whitespace-only decision text in POST /api/memory/{project}/decisions.
• Providing an invalid ISO 8601 timestamp range for timeline queries.
• Submitting malformed citation promotion requests missing required citation_id or target_project.

How to Fix:

1. Inspect the JSON error response: {"detail": "<specific validation error>"}.
2. Ensure Content-Type: application/json is sent in the request header.
3. Validate that required string fields contain at least 1 non-whitespace character.

Common Triggers for 401 Unauthorized:

• Attempting to call protected management endpoints without a bearer token when authentication is active.

Common Triggers for 403 Forbidden:

• Pre-Write Safety Violation: Proposed diff or action triggers a high-severity security rule.
• Safety Budget Exhaustion: An automated agent exceeded its hourly decision creation quota (see Agent Safety Budget).
• Locked Decision Mutation: Attempting to modify or delete a pinned/attested decision without explicit tech lead attestation.

How to Fix:

• If blocked by a safety budget, approve the pending action in the Needs Attention dashboard queue or escalate via POST /api/memory/{project}/agents/{agent}/safety-budget/escalate.
• If authentication failed, ensure your client passes the configured API key header.

Common Triggers:

• GET /api/memory/MyProject: The file memory/MyProject.json does not exist.
• PATCH .../decisions/dec-999/context: Decision dec-999 does not exist in the specified project.
• GET /api/research-feeds/feed-123: The feed ID is invalid or was deleted.

How to Fix:

1. Check the list of active projects via GET /api/projects.
2. If the project was recently deleted, restore it from memory/.trash/<project>.json.
3. Check decision IDs using GET /api/memory/{project} before executing PATCH or DELETE requests.

Common Triggers:

• Duplicate Project: Calling POST /api/memory with a project name that already exists.
• Hash Chain Conflict: Direct manual edits to memory/<project>.json that broke SHA-256 prev_hash links.
• Session Rollback Collision: Attempting to rollback a session that was already reverted.

How to Fix:

• For duplicate project names, choose a unique project identifier.
• For hash conflicts, run the automatic repair endpoint:

  curl -X POST http://localhost:8766/api/memory/<project>/security/backfill-hashes

Common Triggers:

• Sending a string where an integer is expected (e.g., "limit": "ten" instead of "limit": 10).
• Missing a required field in nested objects (e.g. omitting "status" in goal updates).
• Submitting confidence threshold values outside the valid 0.0 to 1.0 range.

How to Fix: Inspect the FastAPI validation error payload:

{
  "detail": [
    {
      "loc": ["body", "confidence"],
      "msg": "Input should be less than or equal to 1.0",
      "type": "less_than_equal"
    }
  ]
}

Update your client request payload to match the OpenAPI specification at /openapi.json.

Common Triggers:

• Agent Mutation Cap: An agent in an infinite coding loop dispatched too many decision requests in a 60-second window.
• Search Engine Rate Limit: Brave Search or Exa API returned 429 due to query quota limits.

How to Fix:

1. For agent limits: Throttle agent execution rate or increase the agent's hourly budget in Agent Safety Budget.
2. For research limits: Tropelex automatically falls back to DuckDuckGo when primary search keys encounter 429 errors.

Common Triggers for 500:

• Corrupted JSON syntax on disk in memory/<project>.json.
• Disk full or file lock contention during high-concurrency writes.

Common Triggers for 503:

• Background scheduler initializing or stopped.
• All web search providers (Brave, Exa, Serper, DuckDuckGo) unreachable due to network outage.

How to Fix:

1. Check the server console log output for python tracebacks.
2. Validate JSON files with python3 -m json.tool memory/<project>.json.
3. Check internet connectivity if running deep research queries.

chevron_rightOperating System Error Codes

• [Errno 98] Address already in use (EADDRINUSE): Another process is listening on port 8766. Kill existing PID via kill -9 $(pgrep -f "core.tropebook.web.server").
• [Errno 13] Permission denied (EACCES): Current user lacks read/write permissions for memory/ or static UI directories. Run chmod -R u+rw memory/.
• [Errno 2] No such file or directory (ENOENT): Required folder memory/ does not exist. Run mkdir -p memory/snapshots memory/tropebook memory/.trash.

chevron_rightCLI & Pytest Exit Codes

• Exit Code 0: Clean termination / all Pytest tests passed.
• Exit Code 1: One or more Pytest tests failed, or fatal CLI argument error.
• Exit Code 2: Process interrupted by user (SIGINT / Ctrl+C).
• Exit Code 4: Pytest command-line usage syntax error.
• Exit Code 5: No tests were collected by Pytest.