Persistent Mind Model

Persistent Mind Model (PMM) is an attempt to model mind as reconstructable continuity.

It began with a thought experiment: strip away embodiment and immediate sensory experience, and ask what could remain of a mind. The answer that motivated PMM was a layered, recursively inspectable history—the capacity to remember, reflect on memory, reconsider earlier reflections, examine how those interpretations were formed, reconstruct an identity from that lineage, and make commitments about who to become.

PMM is therefore not merely persistent context for an agent. It explores how a language-model system can externalize an autobiographical structure in which history acquires meaning through later interpretation, identity can be revised through recursive reflection, ontology can develop, and commitments can extend self-understanding into future conduct.

The current implementation is an event-sourced runtime beneath that aspiration. It records canonical events in SQLite, rebuilds deterministic projections, and selects bounded context for later turns. Its cognitive aspiration is paired with forensic implementation discipline: a claimed change in identity should eventually be traceable through the experiences, interpretations, relationships, commitments, outcomes, and later reinterpretations that produced it.

PMM does not make a model's statements true merely by recording them. A model utterance, a validated event, a projected relationship, and authoritative state are different layers with different guarantees. The originating thought experiment defines the project; it does not establish that a software system is conscious or equivalent to a biological mind.

Start here

• Cognitive Charter — the intended architecture and the boundaries PMM must preserve.
• System Guide — how the current implementation works.
• Current Status and Roadmap — where the project is now and the next selected task.
• Contributing — development and verification rules.

What PMM provides

• A hash-linked event ledger with governed writer ownership.
• Rebuildable Mirror, MemeGraph, and ConceptGraph projections.
• A managed turn protocol that preserves completed assistant output or an explicit generation failure.
• Bounded retrieval over concepts, commitment episodes, graph relationships, summaries, and optional vector similarity.
• Retrieval provenance showing why an event entered model-visible context.
• Structured commitment open, close, reopen, and episode history.
• Conditional validation and promotion for structured claims and identity transitions.
• Interactive, one-shot JSON, and MCP entry points.

The current limits matter just as much: reference policy is not uniform, relational roles are only partially enforced, and PMM does not establish the semantic adequacy of a model-authored interpretation.

Architecture at a glance

model-authored or user-authored input
    -> canonical EventLog history
    -> required rebuildable projections
       (Mirror, MemeGraph, ConceptGraph)
    -> bounded retrieval with provenance
    -> model-visible context
    -> new model output
    -> extraction, validation, and governed state transitions

Current production behavior is described in the System Guide. The Cognitive Charter describes the intended cognitive lifecycle; it is not evidence that every stage is already implemented.

Install

PMM requires Python 3.9 or later.

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[full,dev]"

Run

Interactive client:

pmm

One non-interactive turn using the deterministic dummy adapter:

pmm-turn --db ./pmm.db --provider dummy --prompt "Hello"

One Ollama or OpenAI turn:

pmm-turn --db ./pmm.db --model ollama:llama3 --prompt "What do you remember?"
pmm-turn --db ./pmm.db --model openai:gpt-4o-mini --prompt "What do you remember?"

OpenAI requires OPENAI_API_KEY. Output can be bounded with --output-budget-tokens or PMM_OUTPUT_BUDGET_TOKENS.

Do not run concurrent one-shot writers against the same database. Writer contention is governed and competing managed writers fail explicitly.

Export

From the repository root, use one of the export scripts below. They read the default ledger at .data/pmmdb/pmm.db and write timestamped files to the repository root.

# Export the chat session with telemetry.
python3 scripts/export_session.py

# Export the readable chat, telemetry, and compressed ledger.
python3 scripts/export_session_and_telemetry.py

# Export a smaller telemetry snapshot.
python3 scripts/small_telemetry.py

From the interactive pmm client, export the current chat as Markdown or JSON:

/export md
/export json

MCP

PMM exposes a STDIO MCP server:

PMM_MCP_DB=/absolute/path/to/pmm.db \
PMM_MCP_MODEL=ollama:llama3 \
.venv/bin/python -m pmm.runtime.mcp_server

An MCP client should configure the same command and environment. PMM_MCP_DB is required. PMM_MCP_MODEL is optional and can also use an openai: prefix.

Verify

.venv/bin/pytest -q
.venv/bin/ruff check pmm tests
.venv/bin/black --check pmm tests
git diff --check

Run checks proportionate to the change and report their exact scope. Passing tests corroborate exercised paths; they do not prove that uninspected alternate paths cannot bypass a guarantee.

Research and historical evidence

The repository focuses on current code and current documentation. Historical reports, transcripts, telemetry, and superseded audits remain recoverable from Git history. The publication archive is available through Zenodo.

License

See LICENSE.md.