Tropelex API Reference
Complete HTTP REST API documentation for the Tropelex agent memory system. This reference describes the API — it isn't a live instance. Once you're running Tropelex yourself, the base URL is http://localhost:8766; native JSON endpoints provide state management, causal Q&A, safety auditing, deep research, and Git sync.
database 1. Core Projects & Decisions
/api/projects
Returns a list of all active project memory containers in Tropelex.
curl -s http://localhost:8766/api/projects/api/memory/{project}
Returns full memory details for a project including all decisions, sessions, safety score, and pattern tags.
curl -s http://localhost:8766/api/memory/Tropelex/api/memory/{project}/decisions
Records a new architectural decision. Requires an explicit safety_metadata.safety_category — no silent default. Optionally takes context, citation_ids, and goal_id.
curl -X POST http://localhost:8766/api/memory/Tropelex/decisions -H "Content-Type: application/json" -d '{"decision": "Using FastAPI for REST endpoints", "context": "Provides high performance async processing", "safety_metadata": {"safety_category": "general"}}'/api/memory/{project}/decisions/{id}/context
Backfills or updates rationale context for an existing decision.
curl -X PATCH http://localhost:8766/api/memory/Tropelex/decisions/dec-123/context -H "Content-Type: application/json" -d '{"context": "Updated context with benchmark justification"}'high_quality 2. Quality & Analysis
/api/memory/{project}/insights
Computes decision stats, untagged ratios, ghost drift alerts, and friction metrics.
curl -s http://localhost:8766/api/memory/Tropelex/insights/api/patterns
Auto-detected usage/workflow patterns (e.g. recurring decision categories) and next-step suggestions. Pass ?project= to scope to one project; omitted, aggregates across every project.
curl -s "http://localhost:8766/api/patterns?project=Tropelex"/api/memory/{project}/similar
Finds other projects with similar tech stacks or learned patterns — not similar decisions within one project (see POST .../rag/context below for that).
curl -s http://localhost:8766/api/memory/Tropelex/similaraccount_tree 3. Lineage & Decision Graph
/api/memory/{project}/decision-tree
Returns decision nodes and causal directional links for graph visualization.
curl -s http://localhost:8766/api/memory/Tropelex/decision-tree/api/memory/{project}/rag/context
Retrieves the top_k most relevant decisions for a query, formatted as a single context string ready to inject into a prompt.
curl -X POST http://localhost:8766/api/memory/Tropelex/rag/context -H "Content-Type: application/json" -d '{"query": "why did we choose FastAPI", "top_k": 5}'shield_lock 4. Safety & Governance
/api/memory/{project}/safety-dashboard
Returns composite safety score, active budget balances, and alignment status.
curl -s http://localhost:8766/api/memory/Tropelex/safety-dashboard/api/memory/{project}/needs-attention
Aggregates everything currently waiting on a human for this project: pending reviews, untagged decisions, decayed-confidence items, flagged content, unacknowledged handoffs, and agent-surface findings. Live state meant to be revisited, not a one-time checklist. One source (flagged citations) is intentionally global rather than project-scoped, since Tropebook's citation store isn't split per project.
curl -s http://localhost:8766/api/memory/Tropelex/needs-attentionhistory_toggle_off 5. Sessions & Compaction
/api/memory/{project}
There's no dedicated /sessions endpoint — session history is the session_history field on the full project memory response, alongside decisions, patterns, and everything else.
curl -s http://localhost:8766/api/memory/Tropelex | jq '.session_history'/api/memory/{project}/sessions/record
Records a session summary, triggers pattern learning, and (optionally, via session_shape) baselines this session's tool-call/latency profile against the agent's own history.
curl -X POST http://localhost:8766/api/memory/Tropelex/sessions/record -H "Content-Type: application/json" -d '{"summary": "Built the safety budget endpoint", "agent_name": "Claude"}'/api/compress
Compresses a prompt via the configured LLM backend (falls back to a deterministic dict/concatenation strategy with no key configured). level (1-3) controls aggressiveness.
curl -X POST http://localhost:8766/api/compress -H "Content-Type: application/json" -d '{"prompt": "A very long prompt to shrink...", "level": 2}'science 6. Deep Research & Feeds
/api/research/auto
Runs a search query against the Tropebook citation pipeline and imports results. Global, not project-scoped — citations land in the shared Tropebook store.
curl -X POST http://localhost:8766/api/research/auto -H "Content-Type: application/json" -d '{"query": "vector search reranking strategies", "max_results": 5}'/api/research-feeds
Lists scheduled research feeds. Global by default; pass ?project= to filter to feeds visible to one project (global feeds, feeds it owns, and feeds shared with it).
curl -s "http://localhost:8766/api/research-feeds?project=Tropelex"/api/memory/{project}/decisions/promote
Promotes a candidate decision (typically surfaced by POST .../research/promote-candidates) into a real, recorded decision with citation provenance — goes through the same safety-category gate as any manually-added decision.
curl -X POST http://localhost:8766/api/memory/Tropelex/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"}}'