OrkMind

English · Português

In one sentence: OrkMind is typed, governed memory for AI agents: the rules that matter always reach the model, retrieval is deterministic, and history is never rewritten.

• Status: 0.4.0, alpha · on PyPI as orkmind · changes per version
• Proof: CI on every pull request runs the test suite without a database on Python 3.11 and 3.12, checks the sdist and the wheel, and tests the OpenClaw plugin.
• Project: open source under the MIT license, maintained by Orkastery, contributions by pull request (CONTRIBUTING).
• Language: this page is the canonical entry point, mirrored in Portuguese; part of the docs and the code comments are in Brazilian Portuguese today.

pip install "orkmind>=0.3.0"
bash scripts/setup_postgres.sh        # PostgreSQL + pgvector in Docker (or bring your own)
export ORKMIND_DATABASE_URL="postgresql://orkmind:password@localhost:5432/orkmind"
orkmind add --collection rule --content "Never run rm -rf in production" \
  --tags '{"skill": ["deploy"]}' --mandatory
orkmind search --tags '{"skill": ["deploy"]}'

Why it exists

• Agents keep their memory in instruction files (AGENTS.md, CLAUDE.md, MEMORY.md) that grow until the important rule gets lost in the middle.
• Embedding search is probabilistic: the safety rule you need on this turn may simply not rank.
• OrkMind moves that memory into a typed store with deterministic, tag-based retrieval, and rules marked mandatory are always returned when their tags match the context.

How it works

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

    CC -->|MCP stdio| MCP[MCP server<br/>10 tools]
    HM -->|MemoryProvider plugin| SL
    OC -->|memory plugin| SL
    CL --> SL
    MCP --> SL[SemanticLayer<br/>23 collections &#x2022; 11 tag dimensions]

    SL -->|exact tag search &#43; optional semantic| GS[GovernedStore<br/>protection, ACL, versioning]
    GS --> MS[(PostgreSQL &#43; pgvector<br/>default backend)]

Key concepts

• 23 typed collections: rule, instruction, fact, learning, preference, decision, content, agenda, contacts, handoff, roadmap, files, docs, dags, tools, users, artifact, compliance, semantic_log, session, product, project, initiative.
• 11 tag dimensions: skill, agent, domain, project, situation, person, audience, editors, prod, proj, init. project stays the physical workspace; prod, proj and init model the business portfolio without widening access.
• Deterministic retrieval: exact match on tags. Semantic search (FTS + vector, fused with RRF) is optional and additive, never a replacement.
• Mandatory injection: entries with mandatory: true are always returned when their tags match.
• Token budget: the semantic layer respects a configurable budget and loads critical and mandatory entries first.
• Protection: protected and priority: critical entries reject agent edits and deletes; only human-authenticated sources can change them.
• Append-only history: full version history in memory_versions.
• Anti-injection: suspicious content is kept but excluded from automatic injection, with SHA-256 content integrity.
• Conflict detection: mandatory entries with overlapping tags are held for human review.
• Context layers: progressive loading by fidelity (essence, structure, source).
• Snapshots: commit, log, diff and restore of the whole memory tree.
• Encryption at rest: optional AES-256-GCM for sensitive collections.

Quick start

pip install "orkmind>=0.3.0"

# PostgreSQL + pgvector with the helper script (requires Docker)
bash scripts/setup_postgres.sh
# or on an existing server
createdb orkmind
psql orkmind -c "CREATE EXTENSION IF NOT EXISTS vector;"

Point OrkMind at the database with ORKMIND_DATABASE_URL, or with ~/.orkmind/config.toml:

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

[server]
log_level = "INFO"
token_budget = 4000

orkmind add --collection rule --content "Never run rm -rf in production" \
  --tags '{"skill": ["deploy"], "domain": ["infra"]}' --mandatory
orkmind list --collection rule
orkmind search --tags '{"skill": ["deploy"]}'
orkmind detect --text "Let's deploy the terraform changes"
orkmind stats
orkmind add --collection content --content "weekly report" --dedupe --json   # idempotent

Integrations

The MCP server and the CLI never build a model prompt, so they expose the same rules on demand instead of injecting them. Only the two prompt-building plugins guarantee that governance reaches the model on every turn, and both are covered by the benchmark below.

MCP configuration for Claude Code:

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

Storage backends

OrkMind separates persisting from governing. A backend stores and returns bytes; protection, ACL, versioning and ordering run in one layer above it, identical for every backend.

Every degradation is declared in StoreCapabilities and printed by orkmind store info, never silent. See the backend guide and the capability matrix.

Guaranteed writes

Content written by agents and cron jobs is staged in a durable on-disk queue first and then reconciled, so it survives a missing tool or a database that is briefly down. Idempotency is keyed on the SHA-256 content_hash and enforced by a unique index, so replaying the queue never duplicates memory.

export ORKMIND_API_TOKEN="<token>"
orkmind api --port 8077                           # local idempotent write API, loopback only
python scripts/orkmind_drain.py --once            # drain the queue once (cron)
python scripts/orkmind_drain.py --status          # inspect it without writing

Details in docs/sempre-gravar.md.

Native Memory Provider

orkmind.memory_provider is a separate async package for stacks that need a full memory rather than the rule layer above: three tiers (Core, Recall, Wiki), hybrid dense and lexical retrieval fused with RRF in SQL, deterministic RBAC pre-filtering, and idempotent ingestion of whole documents (Markdown with wikilinks and frontmatter, text, CSV, PDF, DOCX). The database rejects UPDATE and DELETE on the history tables, and an MCP server (python -m orkmind.memory_provider.mcp) exposes memory_search and memory_get.

pip install "orkmind[memory-provider]>=0.3.0"
export ORKMIND_PROVIDER_DATABASE_URL=postgresql://user:password@localhost:5433/memory_provider
python examples/memory_provider.py

See docs/memory-provider/README.md.

Development

pip install -e ".[dev]"
pytest -m "not integration"      # what CI runs, no database needed
pytest                           # the full suite; needs ORKMIND_TEST_DATABASE_URL with "test" in the name

The integration tests erase the database they point at, so the test guard only accepts a database whose name marks it as a test database.

Design decisions

Documentation

• Ontology reference: collections, tag dimensions, validation
• Integration guide: Claude Code and Hermes
• MCP setup · Hermes setup
• Federated memory: per-project stores, shared recall and profile ACL
• Guaranteed writes: spool, drainer, idempotent API
• Native Memory Provider
• Benchmark: method, metrics, and what it does not prove
• Changelog

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.

Project

OrkMind is open source under the MIT license, maintained by Orkastery. Contributions come in by pull request, with the evidence described in CONTRIBUTING. Report vulnerabilities privately, as described in SECURITY. The code of conduct applies to every space of the project.

License

MIT