pentacore

A quest log for AI agents, served over the Model Context Protocol.

An agent without memory goes in circles: it retries what already failed, loses its plan when the context is compacted, and cannot say what was done last week. pentacore is where it writes down what it set out to do, what it tried, what it found and what is left, and where the next session, or the next model, picks that up.

It is a tool, not a manager. It stores what it is given and returns what is asked for.

• One local binary, one encrypted SQLite file. No services to run.
• Built on the official Rust MCP SDK (rmcp).
• Shared by any number of agents and projects at once.

What it stores

| Store | Holds | Found by | |---|---|---| | Notes | Goals, steps, attempts and their outcomes, facts, decisions, open questions, lessons | Words and meaning (recall) | | Entities | Many things of one kind (hosts, endpoints, files), each with a status, attributes and named checks | Field filters (query_entities) |

Notes form a tree through parent and a graph through typed links, which is how a goal is broken down and tracked. A note can point at the entity it is about.

The split matters. "Show every host whose tls check failed" is a query over fields. It should not depend on how somebody phrased a note.

How it is meant to be used

A tree, not a pile. A task is a goal; its parts are steps beneath it; findings sit beneath the step they belong to. Checking example.com is a goal, each subdomain a step.

Done or not done. A step carries a checklist. An item has two states only, so whoever picks the task up later reads what is left without interpreting anyone's status words. For many similar targets, each target is an entity and each check a mark_check, so that "which hosts are left" is one query.

A summary at every level. When a step is finished, summarize writes its one summary and closes it: work, everything that was done, in brief, failures included; result, the outcome in detail. A goal gets its own, written from the summaries of its steps. task_summary returns a task as its summaries in tree order and nothing else, so "what was checked on example.com, and what came of it" costs one call however many notes lie beneath.

How far to trust a note. A note carries confidence (0 to 1) and basis, a sentence or two on what the confidence rests on. They come back with the text wherever the note is read, so the next agent knows how sure the last one was. confirm records that a note was checked again and found true; that is the only thing that sets verified_at. Confidence does not affect ranking.

Lessons. Know-how worth reusing is a note of kind lesson: the problem, what was found, how it was checked, whether it was confirmed, what was done. When a later, better check reaches a different conclusion, the lesson is updated; the earlier text stays as a revision and searches return only the current one.

Handing work down. A lead agent gives part of the work to another agent as a step: the brief goes in its body, and the notes the other agent needs are linked from the step with uses. A note a task uses is context for that task and for every task beneath it, so a scope decision linked from the goal reaches every sub-agent at any depth, and a finding linked from one step reaches only the work under that step. The other agent is told only the step's id and starts with resume task=<id>: the reply's context holds the shared notes, nearest first, with their confidence and basis, followed by the tasks above with their bodies. A shared note that a newer one supersedes or contradicts names it in superseded_by or contradicted_by, as in recall; a dropped one is left out. One call, within the size budget, instead of the lead's whole conversation; budget.omitted counts what did not fit. Results travel back up as summaries.

Search before experimenting. The instructions the server sends tell the agent to look for earlier work first.

Install

Prebuilt binaries

Download the archive for your platform from Releases:

| Platform | Archive | |---|---| | Linux x86_64 | pentacore-<version>-x86_64-unknown-linux-gnu.tar.gz | | Linux arm64 | pentacore-<version>-aarch64-unknown-linux-gnu.tar.gz | | macOS arm64 (Apple silicon) | pentacore-<version>-aarch64-apple-darwin.tar.gz | | Windows x86_64 | pentacore-<version>-x86_64-pc-windows-msvc.zip | | Windows arm64 | pentacore-<version>-aarch64-pc-windows-msvc.zip |

Each archive holds the pentacore binary (pentacore.exe on Windows), this README, the license, the agent usage guide in skills/ and .env.example. The binary is self-contained: SQLCipher and ONNX Runtime are linked in. Unpack it wherever you keep tools.

tar -xzf pentacore-<version>-aarch64-apple-darwin.tar.gz

Platform notes:

• Linux. Built on Ubuntu 24.04 and needs a glibc at least as new: Ubuntu 24.04, Debian 13, Fedora 40 or later. On older systems, build from source or use Docker.
• macOS. The binary is not signed. If it was downloaded with a browser, macOS quarantines it; clear the flag once: xattr -d com.apple.quarantine pentacore. Intel Macs are not supported: ONNX Runtime ships no binaries for them.
• Windows. Needs the Microsoft Visual C++ Redistributable (2015 to 2022), which most systems already have.

From source

Requires Rust 1.88 or newer, and Perl and make for the bundled OpenSSL (on Windows, Strawberry Perl and the MSVC build tools). Builds for the targets above only, for the same reason as the binaries.

git clone https://github.com/DroBov1Tya/PentaCore.git
cd PentaCore
cargo build --release --locked

The binary is target/release/pentacore. Copy it wherever you keep tools.

The first recall downloads the embedding model (all-MiniLM-L6-v2, about 90 MB) into the data directory. Everything works without it, by words.

Connect an agent

pentacore speaks MCP over stdio; the client launches it.

Claude Code

claude mcp add pentacore -- /absolute/path/to/pentacore

Any MCP client (the usual mcpServers block)

{
  "mcpServers": {
    "pentacore": {
      "command": "/absolute/path/to/pentacore",
      "env": {
        "PENTACORE_PROJECT": "my-project"
      }
    }
  }
}

On Windows the command is the full path to pentacore.exe, with backslashes doubled in JSON: "C:\\Tools\\pentacore\\pentacore.exe".

Then give the agent the usage guide in skills/pentacore-memory/SKILL.md. For Claude Code, copy that directory into ~/.claude/skills/ or the project's .claude/skills/. For other agents, include its text in the system prompt.

Run in Docker

docker build -t pentacore:0.7.1 .

MCP runs over stdio, so the client starts the container. The memory lives in a named volume:

{
  "mcpServers": {
    "pentacore": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "pentacore-data:/data",
               "-e", "PENTACORE_PROJECT=my-project", "pentacore:0.7.1"]
    }
  }
}

With Compose, the command is docker compose run --rm -T pentacore (see docker-compose.yml); it adds a read-only root filesystem and drops all capabilities. The container runs as an unprivileged user. Set PENTACORE_PROJECT explicitly: inside a container there is no working directory to name the project after. The first recall needs network access to download the embedding model into the volume.

Configuration

Every variable is optional.

| Variable | Default | Meaning | |---|---|---| | PENTACORE_HOME | ~/.pentacore | Data directory. ~/ means the user's home. Any other relative path is taken from the executable's directory, not the working directory. Created with mode 0700 on Linux and macOS; on Windows it inherits the permissions of its parent directory. | | PENTACORE_PROJECT | name of the working directory | Project used when a call names none. | | PENTACORE_TOOLS | core | core lists the 16 everyday tools to the agent; full lists all 24. Every tool can be called either way. | | PENTACORE_HTTP_ADDR | unset (HTTP off) | Loopback address and port for the HTTP API. | | PENTACORE_HTTP_TOKEN | unset | Bearer token for the HTTP API, at least 32 characters. Required when the address is set. | | RUST_LOG | warn,pentacore=info | Log filter. Logs go to stderr. |

Variables can also come from a .env file beside the executable; see bin/.env.example. A .env in the working directory is ignored on purpose: the working directory may be a checkout you do not trust.

Tools

Listed by default (core):

| Tool | Does | |---|---| | note | Record a goal, step, attempt, fact, decision, question or lesson, with confidence and basis. | | update_note | Change a note. Each change is a new revision; expected_revision refuses a write over someone else's change. | | get_note | One note in full, with children, links and checklist. | | recall | Search notes and entities, most relevant first, repeats shown once. kind narrows it, e.g. to lessons. | | link | Typed links between notes: depends_on, supports, contradicts, answers, supersedes, relates_to, uses. | | graph | The tree beneath a note or an entity. | | resume | State of a project, or with task the area rooted at that task: its brief, summary and freshness, one page of immediate children (id, kind, title, status), checkpoint, open checklist and the context handed down to it, with no size limit: the summary comes whole. Children are paged and never expanded; the tasks above are returned only with include_ancestors. | | checkpoint | Save where the work stands mid-way, for the project or one task. | | checklist | Items on a note that are done or not done. | | summarize | Close a goal or step with its one summary. | | task_summary | Read a task from its summaries alone. | | confirm | Record that a note was checked again and still holds. | | upsert_entity | Create or update by (project, type, key); attributes are merged. | | query_entities | Filter, sort, count and group by column, attrs.<name> or check.<name>. | | mark_check | Record the result of one or several named checks on an entity. | | forget | Purge a note or an entity with every revision. |

Listed with PENTACORE_TOOLS=full:

| Tool | Does | |---|---| | find | Search notes by exact words, with filters. | | get_entity | One entity with checks, children, links, notes about it and its latest events. | | claim_entity | Reserve an entity for one agent, with a timeout; release: true gives it up. | | link_entities | Named links between entities. | | history | Who changed what and when, for a record, a task or a project. Paged by cursor. | | get_revision | The state a note had at an earlier revision. | | redact_history | Purge the earlier revisions of a note, keeping its current state. | | review | What needs attention: stalled tasks, open questions, tasks closed without a summary, open checklist items, low-confidence notes. |

Each tool carries a JSON Schema and MCP annotations (readOnlyHint, destructiveHint).

History

Every change is written to a journal in the same transaction: the record, the kind of change, the names of the fields, and the author, run and task the caller gave. These are labels, not credentials. The journal never holds the text of a record.

Notes keep their full state after each change, confidence and basis included, as numbered revisions. Entities keep their events, with old and new values.

What existed before 0.7 has no recorded history, and none is in