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, the Zapier-compatible endpoint, or Claude writing over MCP. Each item is filed as your own record or as watched library content.

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 (/api/mcp/sse, or Streamable HTTP at /api/mcp/http) exposes the graph to agents; the Explorer and Chat UIs expose it to people.

Use cases

Every imi deployment makes the same five decisions: install, ontology, lanes, inbound, and use. A use-case pack writes down one working set of answers for a kind of work (the domain schema, which sources count as your record, how content arrives, the skills that turn the graph into work) plus a small sample corpus with questions it must answer. Packs are configuration, not code, and they run on a stock install.

you  › Set up imi with the freelance-implementation pack.

Browse them in use-cases/.

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 decides which entity types exist, what extraction looks for, and what the UI calls things, so fitting imi to your business 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:

These four responses are the shared vocabulary of imi's review and judgment services. The design goal in ADR-001 goes further: gate placement and routing declared in domain config, so a gate can run as auto-allow for low-stakes actions and be tightened later without a deploy. That configuration layer is on the roadmap, not yet in the community edition.

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: the only way to change them is an explicit review action (confirm, reject, dispute, supersede), and every one is written to the audit trail with its actor. Review actions are available over MCP as well as in the UI, so on a shared instance, treat review access as a human privilege.

For agent builders, this means you can request search_signals_semantic(authority="instruction") and be certain everything you get back was confirmed in review or imported from a trusted source. Nothing reaches instruction grade just because an agent wrote it.

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. Newer clients can use the Streamable HTTP endpoint at /api/mcp/http instead.

Out of the box, MCP answers only on the machine it runs on. To reach it from other machines on a private network (a VPN or tailnet), or from cloud sessions relayed through your desktop app, see the access tiers guide. The community edition's MCP server has no authentication, so keep it on a network you control.

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: find_changes, get_entity_at_time, get_graph_at_time, and list_claims power questions like "what changed since last week" and "how has this position moved." It's the same machinery behind the world model's current layer.

Configuration

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

Which sources count as your record and which are watched library content lives in config/lanes.yaml. The defaults work without it; copy config/lanes.yaml.example to change them.

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, and any optional model endpoint you choose to configure. 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