rka

Research Knowledge Agent (RKA)

Persistent research memory for AI-assisted investigations.

RKA gives your research project a brain that doesn't forget between sessions. It stores every finding, decision, hypothesis, and literature reference in a structured knowledge base with full provenance chains. The Brain (Claude) handles all knowledge enrichment — no local LLM required.

(A) Three roles — Researcher (frames and ratifies), Brain (Claude Desktop, synthesizes literature and proposes structured options), Executor (Claude Code, implements bounded missions) — share a typed, provenance-aware knowledge base. Four control properties anchor the architecture: traceability, reversibility, visible disagreement, human-ratified commitment. (B) One operational cycle: the Researcher frames a goal; the Brain restates intent (Confirmation Brief), retrieves context, and proposes structured options; the Researcher ratifies a decision; a mission is dispatched to the Executor; the Executor implements and reports back; the Brain integrates results and opens the next decision cycle.

 Month 1                    Month 3                    Month 6
 ┌──────────┐              ┌──────────┐              ┌──────────┐
 │ "We found │              │ "Based on │              │ "We can   │
 │  that..." │              │  3 months │              │  trace    │
 │           │   ┌─────┐   │  of evi-  │   ┌─────┐   │  every    │
 │ (lost     │──▶│ RKA │──▶│  dence..."│──▶│ RKA │──▶│  decision │
 │  next     │   └─────┘   │           │   └─────┘   │  back to  │
 │  session) │              │ (all here)│              │  its why" │
 └──────────┘              └──────────┘              └──────────┘
  Without RKA               With RKA                  With RKA v2
  Findings vanish            Everything persists        Knowledge self-organizes

Built for CS/IoT/CPS security research at UNC Charlotte.

Paper

A working draft describing RKA's architecture, design principles, and evaluation is available as a PDF: RKA-paper.pdf — Framing Is Human: Researcher–Brain–Executor Architecture for AI-Assisted Research.

The figure above is Figure 1 of the draft; it provides a one-glance overview of the architecture (panel A) and one operational decision cycle (panel B). The rest of this README is the practical, hands-on companion: setup, CLI, MCP tools, REST API, and the web dashboard. For the conceptual argument and evaluation, read the draft.

How it works

Three actors collaborate through a shared knowledge base:

graph LR
    PI["🧑‍🔬 PI<br/><i>Human researcher</i>"]
    Brain["🧠 Brain<br/><i>Claude Desktop</i>"]
    Executor["⚡ Executor<br/><i>Claude Code</i>"]
    RKA["📚 RKA<br/><i>Shared knowledge base</i>"]

    PI -->|supervises| Brain
    PI -->|supervises| Executor
    Brain -->|"strategy, decisions"| RKA
    Executor -->|"findings, reports"| RKA
    RKA -->|"context, evidence"| Brain
    RKA -->|"missions, guidance"| Executor

    style RKA fill:#E1F5EE,stroke:#0F6E56,color:#04342C
    style Brain fill:#EEEDFE,stroke:#534AB7,color:#26215C
    style Executor fill:#E6F1FB,stroke:#185FA5,color:#042C53
    style PI fill:#F1EFE8,stroke:#5F5E5A,color:#2C2C2A

• Brain (Claude Desktop) — strategic layer. Interprets findings, decides research direction, reviews evidence clusters, resolves contradictions.
• Executor (Claude Code) — implementation layer. Runs experiments, writes code, collects data. Receives missions, submits reports, raises checkpoints when blocked.
• PI (human researcher) — supervises both, resolves escalations, provides domain expertise.
• RKA — the shared memory. Stores everything, provides context to whoever needs it. A maintenance manifest detects provenance gaps for the Brain to fix.

The knowledge pipeline

Raw observations don't stay raw. The Brain distills journal entries into structured knowledge during maintenance sessions:

graph TD
    Entry["📝 Journal entries<br/><i>note · log · directive</i>"]
    Claims["🔍 Claims<br/><i>hypothesis · evidence · method<br/>result · observation · assumption</i>"]
    Clusters["🗂️ Evidence clusters<br/><i>Grouped claims with<br/>Brain-written synthesis</i>"]
    Map["🗺️ Research map<br/><i>Research questions →<br/>clusters → claims</i>"]

    Entry -->|"Brain extracts"| Claims
    Claims -->|"Brain clusters"| Clusters
    Clusters -->|"Brain synthesizes"| Map

    style Entry fill:#E6F1FB,stroke:#185FA5,color:#042C53
    style Claims fill:#EEEDFE,stroke:#534AB7,color:#26215C
    style Clusters fill:#FAEEDA,stroke:#854F0B,color:#412402
    style Map fill:#E1F5EE,stroke:#0F6E56,color:#04342C