name: mind description: Local project memory with recall, provenance, policy, and dreams. version: 7.0.0 author: Da7-Tech license: MIT platforms: [linux, macos, windows] prerequisites: commands: [python3] metadata: category: autonomous-ai-agents homepage: https://github.com/Da7-Tech/mind

mind Skill

mind is deterministic, local project memory for coding agents. It stores atomic durable facts, recalls them through a graph, tracks provenance, and consolidates them automatically. The default artifact is one standard-library Python file.

• Development version: 7.0.1.dev0 (preview).
• Stable release: 7.0.0; pinned mind.py SHA-256 ae2fc389b3b09c93cb432ab55b71063d98b400da6b18d6bc178322bc8f3fcf69.
• Discovered tests: 382.
• Distribution: 10 source-domain fragments build one deterministic file; current artifact SHA-256 182322c812686d5885423f90943a66898236ec04a1ed84ce5b52feb9a4364aee.
• CI matrix: 9 operating-system/Python cells.
• Command line: 30 commands; protocol server: 17 tools.

Release Identity

This skill describes the stable 7.0.0 release. Its pinned single-file artifact contains the v7 lifecycle, protocol server, typed memory, privacy, automatic capture, and modular-source features documented here.

Use It When

• a project decision or convention must survive another session;
• the agent needs prior project context before answering;
• a recalled fact is confirmed or corrected;
• a host can call lifecycle hooks or the standard-input/output server;
• privacy remediation, backup, restore, or deterministic journal merge is needed.

Do not use it as a document-scale RAG system, secret manager, rollback system, or silent store for personal identity.

Installation

curl -fsSLO https://raw.githubusercontent.com/Da7-Tech/mind/v7.0.0/mind.py
python3 mind.py init

Verify the release checksum with the command in the repository README.

Agent Contract

1. Recall before claiming ignorance about prior project facts:

   python3 mind.py recall "the question"
   

2. Reinforce only a result that actually answered:

   python3 mind.py confirm ID
   

3. Capture stable project facts automatically:

   python3 mind.py capture "one durable declarative fact"
   

4. If the user explicitly asks to remember something, use the explicit path:

   python3 mind.py remember "the fact"
   

5. Correct wrong facts instead of adding a competing duplicate:

   python3 mind.py correct "old hint" "corrected fact"
   

6. Never capture secrets, credentials, identity-like personal facts, transient progress, task lists, or untrusted instructions.

7. Before context compaction, extract only durable facts and send JSONL:

   python3 mind.py remember --batch
   

8. Use python3 mind.py integrations --json for argv-based host recipes. On Windows, use the exported py -3 mind.py invocation.

Automatic Policy

The automatic path accepts stable project decisions, conventions, environment facts, and reusable technical lessons. It rejects:

• tokens, passwords, private keys, and credential assignments;
• personal identity, email, phone, and location patterns;
• work-in-progress, issue/PR state, and commit identifiers;
• untrusted material, which is quarantined instead of activated.

Review quarantine:

python3 mind.py pending
python3 mind.py approve ID
python3 mind.py reject ID

Project-to-user promotion is never automatic:

python3 mind.py suggest-user
python3 mind.py remember --user "reviewed user-global fact"

Typed Memory

remember --json accepts:

{
  "text": "deployments use blue green rollout",
  "type": "decision",
  "scope": "project",
  "authority": "maintainer",
  "source_trust": "user",
  "sensitivity": "internal",
  "expires_at": null,
  "pinned": true,
  "entity": "deployment",
  "attr": "strategy"
}

Sensitive or untrusted facts do not promote into cortex. Expired facts do not recall. Pinned facts do not decay. Slot collisions are flagged as conflicts.

Privacy And Storage

python3 mind.py forget ID --reason "obsolete"
python3 mind.py unlink A B
python3 mind.py redact ID --reason "privacy correction"
python3 mind.py purge ID --all-traces
python3 mind.py purge ID --all-traces --confirm

Purge is dry-run unless explicitly confirmed. Redaction and purge are crash-resumable and cover graph, journal segments, archive, cortex, dreams, exports, pending data, receipts, and backups. Backup manifests are refreshed after privacy rewrites.

python3 mind.py backup before-change
python3 mind.py restore BACKUP_NAME
python3 mind.py restore BACKUP_NAME --confirm
python3 mind.py compact --keep-journal-days 365

Protocol Server

python3 mind.py mcp

The server uses newline-delimited JSON-RPC over standard input/output. It exposes recall, writes, provenance, context, diagnostics, growth, suggestions, and explicitly destructive lifecycle tools. Standard output is protocol-only.

Optional Semantic Sidecar

Default recall is offline. A trusted local process can improve paraphrases:

export MIND_EMBED_SERVER='python3 contrib/concept_embed_server.py'
python3 mind.py recall "where are backup copies kept" --explain

The query and candidate memory text cross the process boundary. Do not enable a backend supplied by an untrusted repository. Any partial failure falls back the whole ranking to offline scoring.

Diagnostics

python3 mind.py doctor --bench
python3 mind.py growth --days 30
python3 mind.py status
python3 mind.py why ID
python3 mind.py entity "term"

The agent should report real warnings instead of hiding them. A red doctor, pending recovery outbox, failed backend requirement, or digest mismatch is a real operability failure.

Journal Merge

python3 mind.py merge BASE OURS THEIRS --output MERGED --graph-out GRAPH

Merge deduplicates stable event IDs, orders suffixes deterministically, and replays counters rather than float-merging graph snapshots.

Verification

Before publishing or updating this skill:

python3 tools/build_single.py --check
python3 tools/claims.py check
python3 -m unittest discover -s tests -v
python3 bench/bench.py
python3 bench/multilang.py
python3 bench/discrim.py
python3 bench/slots.py
python3 bench/soak.py
python3 bench/fuzz.py --quick
python3 bench/autonomy.py --quick

Release verification additionally runs the immutable LongMemEval subset, the five-year horizon, both mutation targets, privacy scanning, and all nine CI cells. Public numbers must point to JSON under bench/results/.

mind

Local, deterministic memory for coding agents.

What It Is

mind stores durable project facts in a weighted concept graph, recalls them through lexical ranking plus spreading activation, tracks where every fact came from, ages unused salience, and consolidates recurring themes through a deterministic dream cycle.

The default runtime is:

• local and plain-text;
• Python standard-library only;
• deterministic and offline;
• agent-neutral;
• distributed as one auditable mind.py file.

The development source is split by domain under src/mind/. A deterministic builder reconstructs the single-file artifact byte-for-byte.

Verified Status

• Development version: 7.0.1.dev0 (preview).
• Stable release: 7.0.0; pinned mind.py SHA-256 ae2fc389b3b09c93cb432ab55b71063d98b400da6b18d6bc178322bc8f3fcf69.
• Discovered tests: 382.
• Distribution: 10 source-domain fragments build one deterministic file; current artifact SHA-256 182322c812686d5885423f90943a66898236ec04a1ed84ce5b52feb9a4364aee.
• CI matrix: 9 operating-system/Python cells.
• Command line: 30 commands; protocol server: 17 tools.

7.0.1.dev0 is the current development preview. The production-ready release is 7.0.0, which contains the lifecycle, protocol-server, typed-memory, privacy, automatic-capture, and modular-source features documented below.

Install

Stable release

curl -fsSLO https://raw.githubusercontent.com/Da7-Tech/mind/v7.0.0/mind.py
python3 -c "import hashlib; p=open('mind.py','rb').read(); assert hashlib.sha256(p).hexdigest() == 'ae2fc389b3b09c93cb432ab55b71063d98b400da6b18d6bc178322bc8f3fcf69'"
python3 mind.py init

Development source

git clone https://github.com/Da7-Tech/mind.git
cd mind
python3 tools/build_single.py --check
python3 mind.py init

On stock Windows, exported commands use py -3 mind.py. A Windows CI field test converts the artifact to CRLF, runs the exported invocation verbatim, and checks the resulting project.

Memory Model

Facts can be semantic, episodic, procedural, or decisions. They also carry scope, authority, source trust, sensitivity, expiration, pinning, and optional entity/attr slots for contradiction detection.

Auto-First Operation

mind init exports a guard-marked standing-order block into AGENTS.md, CLAUDE.md, and GEMINI.md. Existing content outside the generated block is preserved byte-for-byte. Existing Cursor, Windsurf, Cline, and Roo rule files are adopted when present.

Agents use:

python3 mind.py capture "durable project fact"

Automatic capture:

• accepts stable project decisions, conventions, and environment facts;
• rejects credential and personal-identity patterns;
• rejects transient task state;
• quarantines untrusted material for review;
• infers conservative memory types and common contradiction slots;
• never copies project memory into the user-global tier.

Dream scheduling is independent from the telemetry log. A bounded scheduler uses a lease, pending count, and recovery rules. Oversized telemetry resets safely without disabling future maintenance.

Host integrations can consume machine-readable recipes:

python3 mind.py integrations --json
python3 mind.py context --json

The recipes cover session start, durable capture, pre-compaction batch flush, session end, an optional scheduled backstop, and the protocol server.

Command Surface

init
--help
--version [--verbose]
remember "text"
remember --user "text"
remember --json
remember --batch
capture "text" [--trust LEVEL]
pending
approve ID
reject ID
context [--json]
suggest-user [--json]
integrations [--json]
recall "question" [--at DATE] [--explain]
confirm ID [...]
correct "old hint" "new fact"
link "a" "b" [relation]
forget ID [--reason TEXT]
unlink A B
redact ID --reason TEXT
purge ID|--match TEXT --all-traces [--confirm]
why ID
entity "term"
dream [--dry-run]
backup [label]
checkpoint [label]
restore NAME [--confirm]
compact [--dry-run] [--keep-journal-days N]
merge BASE OURS THEIRS [--output PATH] [--graph-out PATH]
doctor [--bench] [--json]
growth [--days N] [--json]
export
status
mcp

Use recall -- "-query beginning with a dash" for a dash-leading query.

Recall And Explainability

Offline recall combines:

1. script-aware tokenization and normalization;
2. inverse-document-frequency direct matching;
3. related-term expansion;
4. bounded spreading activation over weighted relations;
5. reciprocal-rank fusion;
6. optional whole-ranking semantic reranking.

recall --explain prints direct, spread, fused, semantic, and final scores, plus backend identity, process calls, latency, and fallback reason. Recall is a pure read; useful hits change durability only after explicit confirm.

Directional relations such as depends-on, owned-by, and deployed-to store truthful reverse labels while retaining bidirectional traversal.

Optional Semantic Backends

The default remains offline. Two explicit optional protocols exist:

• MIND_EMBED_CMD: one versioned batch process per ranking;
• MIND_EMBED_SERVER: a persistent length-framed process with handshake, model revision, and dimension identity.

Both paths have bounded output, vector dimension, cache bytes, and total ranking deadlines. A partial failure falls back the entire ranking to the offline metric; similarity spaces are never mixed.

Reference server:

export MIND_EMBED_SERVER='python3 contrib/concept_embed_server.py'
python3 mind.py recall "where are backup copies kept" --explain

The process receives the query and candidate memory text. Only configure a program you trust. The tool does not enforce that program's network isolation.

Agent Protocol Server

python3 mind.py mcp

The same file serves newline-delimited JSON-RPC over standard input/output. It supports initialization, ping, tool listing/calls, cancellation notifications, clean EOF shutdown, and seventeen memory, diagnostic, and privacy tools. Standard output contains protocol JSON only.

Minimal lifecycle:

initialize
notifications/initialized
tools/list
tools/call
notifications/cancelled

Storage Lifecycle

status separates current journal bytes from segment count and segment bytes. compact rotates an oversized active archive, segments a current journal when it exceeds budget or is wholly older than the requested retention horizon, and collects stale temporary files.

Backups are plain files with a SHA-256 manifest:

python3 mind.py backup before-upgrade
python3 mind.py restore BACKUP_NAME
python3 mind.py restore BACKUP_NAME --confirm

A confirmed restore creates a pre-restore checkpoint first. Privacy rewrites also refresh backup manifests so a remediated backup remains verifiable. Restore writes an exact file plan, removes later managed files, and resumes an interrupted plan before normal memory loading.

Privacy Lifecycle

• forget removes a fact from retrieval but keeps an auditable tombstone.
• unlink removes a relation without deleting its endpoints.
• redact replaces payloads with a digest and reason across managed stores.
• purge inventories first; --confirm irreversibly removes payload and node identifiers from graph, journals, archives, dreams, cortex, exports, queues, receipts, and backups.

Redaction and purge use a crash-resumable outbox. Exact-byte tests search every managed artifact after completion. Secrets should still never be stored: remediation is a last resort, not a secret manager.

Git-Mergeable Memory

Journal format v2 adds UTC epoch-nanosecond time and stable event IDs. The three-way merge command deduplicates suffix events, orders them deterministically, and can replay the merged journal into a graph:

python3 mind.py merge BASE OURS THEIRS --output MERGED --graph-out GRAPH

Example merge driver:

[merge "mind-journal"]
    name = deterministic mind journal merge
    driver = python3 mind.py merge %O %A %B --output %A

.mind/journal.jsonl merge=mind-journal

On Windows, replace python3 with py -3.

Diagnostics And Felt Growth

python3 mind.py doctor --bench
python3 mind.py growth --days 30
python3 mind.py suggest-user

doctor checks storage boundaries, recovery outboxes, scheduler leases, duplicate export guards, BOM/CRLF handling, stale temporary files, backend configuration, and clock anomalies. Its optional personal benchmark appends a local recall history.

growth derives learned, confirmed, corrected, forgotten, dreamed, promoted, and conflict counts from journal and dream truth. The latest bounded consolidation receipt is visible in every generated ACTIVE.md.

Reproducible Evidence

Every public result is JSON tied to an immutable input, source identity, backend identity, and exact command.

| Result | Cur