Getting Started

checklist Requirements

• Python 3.10+
• uv (recommended) or pip
• OpenAI API key — optional, only needed for AI-backed prompt compression (a dictionary-based fallback works without one)
• Brave Search API key — optional, falls back to the free DuckDuckGo provider

looks_one Clone and install

git clone https://github.com/kylosarc/tropelex.git
cd tropelex

# With uv (recommended)
uv venv
uv pip install -r requirements.txt

# Or with pip
pip install -r requirements.txt

looks_two Set your API key (optional)

Create a .env file in the project root — skip this entirely and Tropelex still runs, with AI compression falling back to dictionary-based rules:

OPENAI_API_KEY=sk-your-key-here
BRAVE_SEARCH_API_KEY=your-brave-key-here   # optional

looks_3 Start the server

python -m core.tropebook.web.server

Then open http://localhost:8766 in your browser.

looks_4 First steps in the dashboard

This mirrors the in-app "Getting Started" checklist (Engine Core sidebar) — the same four steps get you from a blank install to a project that actually has memory worth having:

1. Create a project — the "+ New" button in the top bar. A project is a scoped memory store; you can have as many as you have codebases.
2. Record a decision — Memory tab → "+ Add Decision," or from your own agent/editor via the MCP tools, Emacs integration, or a slash command. This is the seed every other feature (drift detection, ADRs, the decision graph) reads from.
3. Configure API keys — Settings, if you want AI-backed compression or Brave-powered search instead of the free fallbacks.
4. Set up a research feed — Research & Ingestion → Research Feeds, if you want Tropelex to keep pulling outside signal into a project's memory on a schedule instead of only capturing what you feed it manually.

terminal Using it from an AI coding agent

A project-scoped .mcp.json is committed at the repo root, so opening the cloned repo in Claude Code registers the tropelex MCP server automatically — no manual setup. For other MCP clients, or Emacs/OpenCode specifically, see the full Documentation for setup steps.