OrkMind

Semantic memory layer for AI agents. OrkMind offloads memory from constrained agent instruction files (MEMORY.md, AGENTS.md, CLAUDE.md) into a structured, typed store with deterministic tag-based retrieval and mandatory rule injection.

Status: v0.3.0 - Fase 2.5 (Contexto por camadas + recuperacao + autonomia controlada) entregue - 220 testes, camadas E1/E2/E3 com progressive loading, snapshots globais, encryption at-rest seletivo (AES-256-GCM), extracao automatica com guardrail de 3 camadas, busca semantica com rerank RRF. Inclui toda a Fase 2 (governanca, protecao, anti-injection, conflitos, DAG). Ver CHANGELOG.

Architecture

flowchart TD
    subgraph Runtimes
        CC[Claude Code]
        HM[Hermes Agent]
        CL[orkmind CLI]
    end

    CC -->|MCP stdio| MCP[MCP Server<br/>7 tools]
    HM -->|MemoryProvider| HP[Hermes Provider]
    CL --> SL

    MCP --> SL[SemanticLayer<br/>20 collections &#x2022; 8 tag dimensions]
    HP --> SL

    SL -->|exact tag search &#43; semantic| MS[MemoryStore ABC]
    MS --> PG[(PostgreSQL &#43; pgvector)]

    SL --> DET[Context Detectors<br/>Keyword &#43; File path]
    DET -->|inferred tags| SL

    style PG fill:#336791,stroke:#fff,color:#fff
    style SL fill:#2563eb,stroke:#fff,color:#fff
    style MCP fill:#10b981,stroke:#fff,color:#fff

Key Concepts

• 20 typed collections: rule, instruction, fact, learning, preference, decision, content, agenda, contacts, handoff, roadmap, files, docs, dags, tools, users, artifact, compliance, semantic_log, session
• 8 semantic tag dimensions: skill, agent, domain, project, situation, person, audience, editors
• Deterministic tag search: exact match on tags, not probabilistic embedding search
• Mandatory injection: entries with mandatory: true are ALWAYS returned when their tags match the query context
• Token budget: the semantic layer respects a configurable token budget, prioritizing critical and mandatory entries
• Rule protection (D2): entries protected/priority: critical reject agent edits/deletes - only human-authenticated sources can modify
• Append-only versioning (D3): full history via memory_versions table with LRU-based garbage collection
• Anti-injection (D4): 5-category detection, suspicious entries retained but excluded from automatic injection; SHA-256 content integrity
• Conflict detection (D5): mandatory entries with overlapping tags flagged and blocked from injection until human review
• DAG engine (D1): in-memory directed graph with topological sort and cycle detection for rule dependency analysis
• Context layers E1/E2/E3 (D6): progressive loading by fidelity - Essence (~100 tokens), Structure (~2k tokens), Source (full). Mandatory entries always loaded at E3
• Global snapshots (D7): commit/log/show/diff/restore of the entire memory tree with embeddings preserved
• Encryption at-rest (D8): optional, selective AES-256-GCM envelope encryption for sensitive collections (contacts, files, docs)
• Session extraction (D9): automatic memory extraction into soft collections with 3-layer guardrail (prompt + post-parse + ontology validation)
• Semantic search + RRF rerank (D10): optional intent-based search combining FTS + vector with Reciprocal Rank Fusion, keeping deterministic find() intact

Quick Start

Install

pip install -e .

Configure

Set the database URL:

export ORKMIND_DATABASE_URL="postgresql://orkmind:orkmind@localhost:5432/orkmind"

Or create ~/.orkmind/config.toml:

[store]
backend = "pgvector"                                          # default
database_url = "postgresql://orkmind:orkmind@localhost:5432/orkmind"

[server]
log_level = "INFO"
token_budget = 4000

Storage backends

OrkMind separates persisting from governing. The backend stores and returns bytes; governance (entry protection, ACL, versioning, constitutional ordering) runs in a layer above, identical for every backend. Switching backends changes where data lives, never what the product guarantees.

export ORKMIND_STORE_BACKEND=qdrant
export ORKMIND_STORE_OPTIONS='{"url": "http://localhost:6333"}'
pip install "orkmind[qdrant]"

orkmind store info          # active backend, capabilities and active warnings

Every degradation is declared in StoreCapabilities and printed by orkmind store info -- never silent. Full matrix in docs/storage-backends/MATRIZ-BACKENDS.md, configuration and migration guide in docs/storage-backends/GUIA-BACKENDS.md.

Set Up PostgreSQL

# Using the helper script (requires Docker):
bash scripts/setup_postgres.sh

# Or manually:
createdb orkmind
psql orkmind -c "CREATE EXTENSION IF NOT EXISTS vector;"

CLI Usage

# Add a memory
orkmind add --collection rule --content "Never use rm -rf in production" \
  --tags '{"skill": ["deploy"], "domain": ["infra"]}' --mandatory

# List memories
orkmind list --collection rule

# Search by tags
orkmind search --tags '{"skill": ["deploy"]}'

# Detect context from conversation
orkmind detect --text "Let's deploy the terraform changes"

# Statistics
orkmind stats

# Add idempotently (returns the existing id instead of duplicating)
orkmind add --collection content --content "relatorio semanal" --dedupe --json

Guaranteed Writes (spool + drainer)

Agent and cron content must never be lost, even when the execution tools are missing from a job toolset or the backend is momentarily down. The write path stages to a durable on-disk queue first, then reconciles:

# Serve the local idempotent write API (loopback only, token required)
export ORKMIND_API_TOKEN="<token>"
orkmind api --port 8077

# Drain the queue once (cron), or continuously
.venv/bin/python scripts/orkmind_drain.py --once
.venv/bin/python scripts/orkmind_drain.py --watch --interval 60

# Inspect the queue without writing anything
.venv/bin/python scripts/orkmind_drain.py --status

Idempotency is keyed on content_hash (SHA-256) and enforced by a partial unique index on memories(collection, content_hash), so reprocessing the queue never duplicates memory. See docs/sempre-gravar.md.

MCP Server (Claude Code)

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "orkmind": {
      "command": "python",
      "args": ["-m", "orkmind.mcp"],
      "env": {
        "ORKMIND_DATABASE_URL": "postgresql://orkmind:orkmind@localhost:5432/orkmind"
      }
    }
  }
}

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check .

# Type check
mypy src/

Design Decisions

Documentation

• Ontology Reference -- 20 collections, 8 tag dimensions, validation
• Integration Guide -- Claude Code + Hermes setup
• MCP Setup -- MCP server configuration for Claude Code
• Hermes Setup -- Hermes MemoryProvider configuration
• Gravacao garantida -- spool, drainer, idempotent API
• Benchmark -- method, metric definitions, and what it does not prove
• Roadmap -- Post-MVP phases and planned features
• Changelog -- Release history

Benchmark

Numbers below are generated by python bench/run.py and read from bench/results/latest.json. They are never typed by hand. Every fraction is reported as hits/total (rate), never as a bare percentage. See bench/README.md for the method and for what this benchmark does not prove.

Last run: 2026-09-01T01:41:27.622062+00:00 at commit 31e4e4f.

M4 recall/precision are deliberately omitted from this table: with a fake embedder they measure nothing about semantic quality. What is validated here is the pipeline structure. Real-embedder numbers are scheduled for the next cycle.

M7 (cross-harness fidelity): rules block identical, 0 differing chars, guardrail present in both.

Support matrix per integration

MCP and CLI never build a model prompt, so unconditional injection does not apply to them: they expose the same rules on demand. Only the two prompt-building integrations can guarantee that governance reaches the model on every turn, and only those are benchmarked.

License

Apache 2.0