Idea Published

Versioned Project Memory

Thesis

A software project should have memory.

Not "documentation". Not "Slack history". Not "ask Pete, he left two years ago".

Actual operational that can answer:

Why did we build this?

And not by guessing from source code, but by tracing the chain:

source knowledge → decision → spec → acceptance criterion → code → evidence → incident/review.

Problem

Code remembers the final shape of a decision.

It does not remember the reason.

A year later, you see:

git blame payment.ts
commit: afgjksfgakjsdl
message: fix edge case

Great. Very useful.

The code says what changed. The project forgot why it changed.

This is the gap Coherence can fill.

Existing Coherence Primitives

Coherence already has the important pieces:

specs
acceptance_criteria
acceptance_criterion_concerns
spec_relations

And the DSL already lets us describe intent as a changelist instead of manually editing database rows one by one.

Example:

coherence_slice! {
    changelist "payment-api-auth" {
        reason: "Payment API requests require an authenticated client and explicit permission checks."

        source rfc: "Internal API contract: Payment API"
        source doc: "Internal security review: payment authorization"

        spec "Payment API requires authenticated client" {
            level: System
            status: Active

            ac "Reject unauthenticated payment request" {
                review_mode: Automated
                risk: High
                concerns: [Security]

                links {
                    implemented_by file "src/payment/api/create_payment.ts"
                    verified_by test "tests/payment/create_payment_requires_auth.test.ts"
                }
            }
        }

        memory "Decision accepted after security review" {
            kind: decision
            actor: "security-review"
            reason: "Unauthenticated payment requests create direct financial and audit risk."
        }

        context {}
    }
}

This changelist can compile into normal relational records.

That matters because once intent is data, it can be reviewed, diffed, queried, linked, and versioned.

Add One Layer: Project Memory

The memory layer should not replace the intent graph.

It should sit above it.

knowledge graph -> intent graph -> code/evidence
        \              \
         \              -> memory events
          -> memory events

Concrete tables:

CREATE TABLE knowledge_sources (
  id VARCHAR(128) PRIMARY KEY,
  kind VARCHAR(32) NOT NULL,
  title TEXT NOT NULL,
  url TEXT,
  content_hash VARCHAR(128),
  captured_at TIMESTAMP NOT NULL
);

CREATE TABLE memory_events (
  id VARCHAR(128) PRIMARY KEY,
  kind VARCHAR(32) NOT NULL,
  summary TEXT NOT NULL,
  reason TEXT,
  actor VARCHAR(128),
  occurred_at TIMESTAMP NOT NULL
);

CREATE TABLE memory_event_links (
  event_id VARCHAR(128) NOT NULL,
  target_type VARCHAR(64) NOT NULL,
  target_id VARCHAR(128) NOT NULL,
  relation VARCHAR(64) NOT NULL,
  PRIMARY KEY (event_id, target_type, target_id, relation)
);

CREATE TABLE memory_embeddings (
  owner_type VARCHAR(64) NOT NULL,
  owner_id VARCHAR(128) NOT NULL,
  embedding VECTOR(1536),
  model VARCHAR(128) NOT NULL,
  content_hash VARCHAR(128) NOT NULL,
  PRIMARY KEY (owner_type, owner_id, model)
);

Now memory is not a blob of text.

It is linked project history.

An incident can link to a spec. A spec can link to an acceptance criterion. An acceptance criterion can link to code. A code location can link to CI evidence. A decision can link to external knowledge.

Commit the Brain

When Coherence accepts a changelist, it writes all related records in one transaction:

START TRANSACTION;

INSERT INTO knowledge_sources (...)
VALUES (...);

INSERT INTO specs (...)
VALUES (...);

INSERT INTO acceptance_criteria (...)
VALUES (...);

INSERT INTO memory_events (...)
VALUES (...);

INSERT INTO memory_event_links (...)
VALUES (...);

CALL DOLT_ADD(
  'knowledge_sources',
  'specs',
  'acceptance_criteria',
  'memory_events',
  'memory_event_links'
);

CALL DOLT_COMMIT(
  '-m',
  'decision: require authenticated client for payment API'
);

This is not theoretical. Dolt already supports exactly this workflow — DOLT_ADD() stages tables, DOLT_COMMIT() snapshots the working set into a new commit with a message (docs). The same procedures work for any schema: specs, acceptance criteria, knowledge sources, memory events — all versioned in a single transaction. Dolt's vector-index documentation shows these snapshots can branch experiments over vector datasets and roll back changed search behavior, confirming the pattern: vectors are the recall index, Dolt is the versioned source of truth.

That Dolt commit is now a snapshot of the project brain.

Not just the code, specs, docs.

The whole reasoning state.

Time Travel

A year later, someone asks:

Why do we reject unauthenticated payment requests?

Coherence can query the current graph:

SELECT
  m.summary,
  m.reason,
  l.target_type,
  l.target_id
FROM memory_events m
JOIN memory_event_links l ON l.event_id = m.id
WHERE l.target_type = 'acceptance_criterion'
  AND l.target_id = 'ac.payment.reject_unauthenticated_request';

But the more interesting query is historical:

SELECT *
FROM acceptance_criteria AS OF 'HEAD~100'
WHERE id = 'ac.payment.reject_unauthenticated_request';

Or:

SELECT *
FROM dolt_history_acceptance_criteria
WHERE id = 'ac.payment.reject_unauthenticated_request'
ORDER BY commit_date;

Or:

SELECT *
FROM dolt_commit_diff_acceptance_criteria
WHERE from_commit = HASHOF('HEAD~1')
  AND to_commit = HASHOF('HEAD');

That gives us a real answer to:

When did this intent change? Who changed it? What else changed in the same commit? Which memory event explains it? Which source knowledge justified it?

This is not RAG over vibes.

This is versioned reasoning.

Vectors Are an Index, Not the Source of Truth

Semantic search is still useful.

You want to ask:

Why did we change payment authorization behavior?

And find related decisions even if the exact words do not match.

So memory records can have embeddings.

But embeddings should not be the durable source of truth.

The durable source of truth is relational:

memory_event
memory_event_links
spec
acceptance_criterion
knowledge_source
code_location
evidence

The vector index is just the fast recall path.

The answer still comes from versioned records.

Why This Is Amazing

Most engineering systems preserve artifacts.

Git preserves files. CI preserves logs. Issue trackers preserve tasks. Docs preserve narratives. Slack preserves noise 🤣

But the actual project brain lives between them.

Coherence can make that brain explicit.

And if the brain is stored in Dolt, it becomes:

diffable
branchable
mergeable
reviewable
queryable
time-travelable

That unlocks a new workflow:

git diff over code
dolt diff over intent
dolt diff over memory

Now a reviewer can ask:

This code changed. Did the intent change? This spec changed. Was there evidence? This incident happened. Which acceptance criteria were updated? This external knowledge changed. Which product decisions depend on it?

Killer Feature

time travel for project understanding.

You can go back to the exact moment when the project believed something different.

Then ask:

What did we know? What did we decide? What did we change? What did we verify? Why did we think this was correct?

That is project memory.

And once project memory is versioned, "why did we do this?" stops being archaeology.