mind

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/.