imi

How it works

Everything that enters imi moves through one pipeline: raw text in, queryable knowledge out. Each stage is inspectable, and every promotion is audited.

1. Ingest

   Documents, commits, and transcripts arrive via upload, webhook, or the Zapier-compatible endpoint.

2. Classify + extract

   Claude classifies the content and pulls out entities and relationships, guided by your active domain schema.

3. Observation model

   Extractions are recorded as observations: the raw, source-linked layer of what was said and where.

4. Signal promotion

   Observations become typed signals (decisions, action items, key points) after passing through governed approval gates, with an audit trail.

5. Knowledge graph

   Entities and signals land in Neo4j (or the in-memory fallback), linked, versioned, and queryable, including point-in-time queries like "what changed since last week."

6. Query anywhere

   The MCP server at /api/mcp/sse exposes the graph to agents; the Explorer and Chat UIs expose it to people.

Domain schemas

imi doesn't hard-code what an "entity" is. A domain schema tells the extraction pipeline what matters in your world (clients, campaigns, cohorts, deals) and the graph shapes itself accordingly. Six example domains ship in config/domains/; copy one and make it yours.

Select one with ACTIVE_DOMAIN=consulting_firm in your .env. The schema drives extraction, routing, and approval-gate placement, so adding a new signal type is a config change, not a code change.

The world model

imi's organizing idea: your team's knowledge is presented as a world model, two layers of one surface, kept honest by a governed review ritual.

Most knowledge tools fail the same way: they become a place where documents go to die. imi avoids that by never treating everything as equally true. Knowledge lives in one of two layers, and only a human moves things between them.

This structure is also the answer to the surveillance question: how does a tool that reads your meetings avoid being creepy? The machine only ever surfaces discrepancies ("this seems to have moved since you decided X"); it never enforces. A human decides what becomes truth. The architecture is a compass, not a camera.

A constitution view, a commitment-health view, a drift alert, and a pre-meeting brief all fall out of this as different views into the same object. The full concept doc lives at docs/world-model-concept.md.

Signals & decision records

The pipeline's core distinction (ADR-001): a Signal is a raw, ephemeral observation. "Someone said X in this meeting." It's unverified, may be contradictory, and carries no authority. A DecisionRecord is the promoted, structured artifact a signal can become. A signal graduates only when it has been:

• Verified Checked against existing context, with no unresolved contradiction.
• Attributed Tied to an authoritative source: a named decision-maker, not just an observation.
• Explicitly promoted By human approval, or by the signal promoter clearing a confidence threshold. One service owns this path; nothing else writes decision records.

Decision records are immutable: corrections happen by superseding, never by editing. That's what makes the audit trail trustworthy, and it's why the demo answer above can show a decision's full lineage.

Approval gates

Wherever the system would take a consequential action, like promoting a signal or mutating an entity other agents read, a human-in-the-loop gate is inserted. Every gate accepts exactly four responses, and agents must handle all of them:

Gates and routing are declared in domain config, not scattered through application code. A gate can be set to auto-allow for low-stakes actions and tightened later without a deploy, and the routing table stays auditable, testable, and readable by non-engineers.

The authority model

Lifecycle (active → stale → superseded) is one axis. The second, orthogonal axis (ADR-002) is trust: where a piece of knowledge came from, and whether an agent may act on it versus merely cite it. Every governed record carries two independent flags:

The rule is enforced at the data layer, not per caller, so no code path can mint instruction-grade content without confirmed provenance. Authority fields are server-injected and never accepted from client input: an MCP client cannot self-promote its own writes.

For agent builders, this means you can request search_signals_semantic(authority="instruction") and be certain you are never handed unconfirmed, agent-generated content. Your agent can act on what it gets back.

Quickstart

The install is Docker-only; no local Python or Node needed. You'll want Docker 24+ with Compose v2, an Anthropic API key, ~2 GB of free RAM, and ports 8080, 7474, and 7687 free on the host.

1. Clone and configure

git clone https://github.com/sufficiently-advanced-ai/imi.git
cd imi
cp .env.example .env

In .env, set the two required values. Every other variable has a working default:

ANTHROPIC_API_KEY=sk-ant-...
NEO4J_PASSWORD=choose-any-password

2. Build and start

docker compose up -d --build

3. Verify it's running

The app waits for Neo4j to pass its healthcheck before starting, so startup is not instant. Expect 1–2 minutes after the build finishes.

docker compose ps                              # both containers → "healthy"
curl -fsS http://localhost:8080/health && echo " OK"

The web UI is at http://localhost:8080. No auth wall by default.

4. Ingest something

Use the Explorer UI at /explorer, or go straight to the API:

curl -X POST http://localhost:8080/api/ingest \
  -H "Content-Type: application/json" \
  -d '{"content": "# My notes\n...", "title": "My notes", "content_type": "document"}'

# Drop in a call transcript (Zapier-compatible endpoint)
curl -X POST http://localhost:8080/api/ingest/zapier \
  -H "Content-Type: application/json" \
  -d '{"provider": "grain", "transcript": "...", "title": "Kickoff call"}'

Connect via MCP

imi's real interface is the Model Context Protocol. Point Claude Desktop, Claude Code, Cursor, or any MCP-compatible client at your running instance and query the knowledge graph in natural language.

{
  "mcpServers": {
    "imi": {
      "type": "sse",
      "url": "http://localhost:8080/api/mcp/sse"
    }
  }
}

A template ships in the repo as .mcp.json.example.

The tool surface

Tools follow a strict verb taxonomy (conventions doc) so an agent can predict what a tool does from its name:

Temporal queries are first-class: get_state_at, what_changed, and point-in-time graph views power questions like "what changed since last week." It's the same machinery behind the world model's current layer.

Configuration

See .env.example for the full list. The minimum set:

Editions

The community edition is MIT licensed and fully self-hosted. Your data never leaves your infrastructure except for the Claude API calls that power extraction. It covers the whole core: text in, governed graph out, agents on top. A hosted service from Sufficiently Advanced AI adds the live-meeting layer on top of the same engine.

In the community edition, batch transcript ingestion covers the meeting workflow: record with any tool you already use, then drop the transcript in by hand, by API, or by Zapier. For live capture and the rest of the hosted column, see sufficiently-advanced.ai.

Docs & contributing

The design record lives in the repo. Start with the ADRs, then the concept docs. Issues and PRs are welcome.

• Architecture Decision Records Why the system is shaped the way it is, decision by decision docs/adr/
• The world-model concept The two-layer model and promotion ritual, in full docs/world-model-concept.md
• Memory governance & retrieval The memory and signal system, end to end docs/prd/
• MCP tool conventions Verb taxonomy, parameter conventions, and surface choice docs/mcp_tool_conventions.md
• MIT License Permissive, with one LGPL library dependency noted in the README LICENSE