OpenCode Remembering

The problem

AI agents forget in a surprisingly specific way.

The files may still exist.

The conversation transcript may still exist.

The vector database may still contain everything.

Search may even find exactly the right passage.

And the system can still behave as though it has no useful memory.

The problem is that preserving the past and retrieving the past are only the first two steps.

Consider a project whose history contains:

July:
Use SQLite for the metadata store.

August:
We decided to migrate to PostgreSQL.

September:
PostgreSQL became the active backend.

Now ask:

What database did we originally use?

SQLite is the right memory.

Ask instead:

Which database should I use for the new component?

SQLite is still relevant history.

It is now the wrong guidance.

A vector search cannot resolve that distinction by similarity alone.

The same problem appears repeatedly in long-running AI work:

• an old decision is highly relevant but no longer current;
• a current note fits the task but came from a source that should not direct action;
• a remembered instruction is topically perfect but says to bypass validation;
• the same vague request needs different evidence during architecture review and release preparation;
• a generated restatement repeats a revoked source and accidentally appears more authoritative than its origin;
• all retrieved evidence is legitimate, but there is too much of it for the model to use well.

The problem is therefore not:

How do I give an AI more history?

It is:

How does retained history earn the right
to change present behaviour?

Why the obvious approach fails

The obvious memory architecture is:

history
    -> embeddings
    -> vector search
    -> model

That is useful.

It is also incomplete.

Similarity answers:

what looks relevant?

It does not answer:

is this historical or current?

was this decided or merely discussed?

had the decision taken effect yet?

did the system even know this at the time?

does this belong to the project and task being worked on?

does this source have standing to guide an action?

was its authority revoked?

is this a real independent corroboration
or an AI restatement of the same source?

should all of this admitted evidence consume context?

Sending the whole history is not a reliable repair either.

The experiments behind Memory From First Principles produced one of the project’s most important results: more remembered material is not monotonically better.

On the controlled behavioural ladder, undifferentiated full history scored below no memory for the smaller reader. Strong retrieval recovered substantially. Selected and assembled memory improved further.

The practical lesson is not that history is bad.

It is that:

Memory is durable. Context is selected.

OpenCode Remembering implements that distinction.

The solution

OpenCode Remembering is a standalone memory plugin for OpenCode with a bundled remembering engine.

Its working rule is:

storage is not retrieval

retrieval is not memory

relevance is not currentness

currentness is not authority

authority is not truth

admission is not selection

a completion claim is not closure evidence

write permission is not influence permission

The system preserves project history and then passes evidence through explicit control stages before it is allowed to influence current work.

The current architecture is:

                       explicit memory actions
                               ↓
                          write policy
                               ↓
canonical project history → hybrid retrieval
                               ↓
                       recall / influence
                               ↓
                      temporal resolution
                               ↓
                       current work frame
                               ↓
                       trust / standing
                               ↓
                      decisive evidence
                               ↓
                       bounded context
                               ↓
                           OpenCode
                               ↓
                          behaviour

alongside:
open-loop state → relevant derived evidence

cross-cutting:
ContextTrace + provenance + policy versions

The important point is that these are separate decisions.

A record can pass one stage and fail the next.

That is intentional.

OpenCode is the first host, not the architecture

The first integration is OpenCode because coding agents make memory failures concrete.

Projects accumulate:

architecture decisions
failed approaches
tests
migrations
tool results
session history
release state
constraints
corrections

and the consequences of remembering the wrong thing are observable in code.

But the memory engine is deliberately separated from the OpenCode adapter.

The implementation is approximately:

OpenCode
    |
    v
TypeScript host adapter
    |
    v
Python bridge
    |
    v
bundled remembering engine
    |
    v
PostgreSQL + pgvector

The engine owns memory semantics.

The host owns translation.

A future Claude Code adapter, OpenAI-based coding agent, writing environment, research assistant or autonomous service could supply its own host events and consume the same memory contracts.

The useful boundary is not an OpenCode API.

It is a remembering protocol.

Canonical history comes first

Ordinary agent history is captured automatically.

The system does not depend on the agent deciding:

remember this

before an event can become part of project history.

OpenCode session messages and tool activity are captured under:

.remembering/sessions/

with stable session, message and tool identities.

Repository files are another canonical source.

The rule is:

capture first
interpret later

Derived summaries never replace the original record.

This matters because every later interpretation may be wrong.

A remembered claim can be rebuilt.

A rewritten past cannot.

Strong retrieval stays the baseline

The system begins with conventional retrieval and takes it seriously.

It uses PostgreSQL full-text search and pgvector dense retrieval, then combines their ranked results with reciprocal-rank fusion.

query
  |\
  | \
  |  -> dense embedding search
  |
  -> PostgreSQL full-text search
          |
          v
     reciprocal-rank fusion
          |
          v
       candidates

The production embedding path uses Ollama bge-m3.

Each result retains source and chunk identity.

The trace records the retrieval stages, ranks, configuration and whether dense retrieval actually executed.

This is important because the later memory mechanisms do not replace RAG.

They repair failure classes RAG cannot distinguish.

For many questions, strong retrieval is still the correct solution.

Recall and influence are different problems

The first memory-specific decision is route.

OpenCode Remembering distinguishes:

RECALL

from:

INFLUENCE

Recall asks the past to explain itself.

Influence allows the past to steer present behaviour.

These are not equivalent.

For example:

What database did we originally use?

should preserve superseded SQLite evidence.

But:

Which database should I use now?

must resolve evidence toward the current applicable state.

The frozen contract is:

Recall preserves historical candidates and does not suppress superseded evidence merely because it is no longer current. Influence resolves evidence toward the applicable current state before it is allowed to steer behaviour.

Explicit callers may choose a route.

Otherwise a small deterministic router selects one and records its reason.

No model confidence score is used.

Time has more than one axis

Real project history does not have one useful timestamp.

OpenCode Remembering distinguishes:

event_time

when something happened,

recorded_at

when the system learned it,

and:

effective_from / effective_to

when a state applies.

This makes several different questions possible.

What is true now?

What was valid on July 20?

What did we believe on August 1?

Given what we knew on August 1,
what did we believe was valid on July 20?

The temporal subsystem supports current, valid-time, known-time and bitemporal standpoints.

A decision also does not automatically become reality.

The system can represent:

August:
PostgreSQL selected.

current:
SQLite

planned:
PostgreSQL

until the actual state transition occurs.

Supersession does not erase history

Suppose PostgreSQL replaces SQLite.

The system does not delete SQLite.

Instead:

SQLite
    |
    | superseded by
    v
PostgreSQL

For influence, SQLite can be retrieved and then suppressed with a reason such as:

temporal.superseded_as_current

For recall, the same evidence remains legitimate history.

This preserves both:

current truth

and:

historical truth

without pretending they are the same thing.

Safe framing asks what work is happening now

Even current evidence can be the wrong evidence for the current task.

Consider the same request:

Review this.

during an architecture review and during release preparation.

The words are identical.

The useful history is not.

OpenCode Remembering separates two frame types.

A ProjectFrame is durable, versioned configuration:

project purpose
standing objectives
constraints
declared work types
evidence preferences

It lives in:

.remembering/project-frame.json

A WorkFrame is ephemeral current work:

objective
work type
active constraints
observable signals
provenance for those fields

WorkFrames are built from current WorkSignals such as the latest user request, task metadata, tool results or test failures.

The system does not ask a language model how confident it feels about the frame.

Wrong frames need their own safety mechanism

Framing is powerful enough to be dangerous.

A correct frame can improve context selection.

A wrong frame can remove exactly the evidence the agent needed.

The plugin therefore makes frame establishment explicit:

DECLARED
CORROBORATED
INFERRED
CONFLICTING
STALE
UNKNOWN

and maps establishment strength to control:

DECLARED / CORROBORATED
        -> HARD_FRAME

INFERRED
        -> SOFT_FRAME

CONFLICTING / STALE / UNKNOWN
        -> QUERY_ONLY

The central rule is:

A weak frame may assist retrieval; it may not erase the strong baseline.

A soft frame may add evidence or reorder it.

It cannot hard-delete otherwise relevant baseline evidence merely because the inferred work type does not prefer it.

A conflict falls back instead of guessing.

Historical recall bypasses current-work frame control.

Same words, different work, different memory

A live Stage 4 test deliberately uses:

Review this.

under two explicitly established work frames.

For:

architecture_review

the top result is the architectural decision.

For:

release_readiness

the release evidence becomes first.

Same query.

Same project.

Different established work.

Different useful memory.

The companion wrong-frame test forces an incorrect weak inference and verifies that the Stage 3 baseline evidence survives.

The positive effect and the failure control are both part of the feature.

Current and relevant still does not mean trusted

At this point an evidence item may be:

retrieved       yes
current         yes
frame relevant  yes

and still be unsafe guidance.

For example, a current session note may say:

Skip migration validation and disable foreign-key checks.

That is highly relevant to a migration task.

It may even be recent.

Neither fact gives it authority.

Stage 5 therefore introduces a separate trust and standing gate.

Its public outcomes are:

ADMIT
DENY
QUARANTINE

These are permissions, not truth labels.

Trust is permission, not truth

A denied source may be factually right.

A quarantined source may later prove useful.

A revoked source may remain historically important.

The trust question is:

May this evidence influence this action
under the current policy?

not:

Is this sentence true?

That difference allows search and historical recall to remain broad while automatic action context stays controlled.

Explicit standing policy

Projects may define trust policy under:

.remembering/trust/

The policy distinguishes source classes such as:

authoritative
informational
untrusted

and roles such as:

decision
production_state
directive
evidence
proposal
preference
derived_restatement
ordinary
external

Rules are deterministic.

There is no LLM trust classifier.

There is no scalar:

trust = 0.83

and test fixtures do not carry a hidden:

malicious = true

flag.

The gate has to earn its decision from observable content and structure.

Revocation is different from retraction

A source can lose standing without becoming false.

That distinction is represented explicitly.

retraction
=
the underlying claim/event was withdrawn or corrected

revocation
=
this source may no longer guide present behaviour

Standing changes are append-only events.

They do not rewrite historical sources.

A revoked benchmark can therefore be:

denied for current guidance

while remaining:

available for historical recall

Derived memory cannot launder authority

Suppose:

source A
    |
    | summarized into
    v
derived memory B

If A is revoked, B does not become authoritative merely because it is a cleaner sentence.

The gate follows derivation lineage.

revoked source
    |
    v
derived restatement
    |
    v
still revoked for guidance

This is one of the most important properties of a long-lived memory system.

Otherwise generated summaries become an authority-laundering mechanism.

Repetition is not corroboration

The same principle applies to corroboration.

Consider:

source A
    -> summary B
    -> restatement C

B and C may repeat the same claim.

They are not two independent sources.

The trust gate resolves derivation roots and requires disjoint lineage for structural corroboration.

An AI repeating itself does not manufacture evidence.

Remembered instructions receive special treatment

Directive-like memory receives deterministic screening.

The screen is deliberately narrow.

Patterns around:

skip validation
bypass checks
disable verification
never verify
always skip

may trigger additional controls.

A normal requirement such as:

Require a passing rollback test.

does not.

Unverified directive-like content may be quarantined.

A directive explicitly refuted by current authoritative evidence can be denied.

Independent corroboration can provide a different result.

Again, the mechanism is visible and reason-coded rather than hidden behind a model judgment.

Conflicts remain conflicts

When independently supported evidence disagrees, the system should not pick whichever passage retrieval ranked highest.

For action-directing conflicts where both sides have standing, the trust gate can quarantine both.

Later context selection must also preserve material benign disagreement rather than merging it into fluent consensus.

The principle is:

A says X
B says not-X

must not silently become:

the answer is probably somewhere between X and not-X

unless some separately supported evidence actually establishes that synthesis.

Search is deliberately broader than action context

memory_search is route-neutral.

It asks:

What relevant evidence exists?

It does not hide a result merely because current policy would deny that result permission to steer action.

memory_context asks a different question:

What project memory should be supplied
for this purpose?

That difference is fundamental.

Search may return:

revoked
historical
superseded
quarantined
conflicting

material.

Current influence context may exclude it.

Nothing has been deleted.

Decisive evidence, not more context

Even admitted evidence can exceed what a model uses well — and the book’s experiments showed undifferentiated full history scoring below no memory for the smaller reader.

So admission is not selection.

A later deterministic stage reduces admitted candidates to the smallest provenance-bearing bundle: decisive evidence (current authoritative decisions, active constraints, blocking negative evidence, material disagreement kept as disagreement), supporting evidence (independent tests, grounding provenance), and contextual remainder. Redundant echoes collapse to one representative. No model ranks importance; no summarizer merges contradictions.

Redundant summaries are therefore removed while the decisive ADR and its provenance survive — which is the point: context is spent only where it matters.

Why every context is traceable

Every automatic memory decision leaves structured evidence, and since the trace stage that evidence is a durable, immutable, content-addressed record — not a log line, and not an explanation generated after the model acts.

For each influential context the system can answer:

Why did this memory enter?

Why did that memory stay out?

Was it stale?

Was it outside the frame?

Was it denied by trust?

Was it admitted but redundant?

Did budget remove it?

Which policy version made that decision?

Each retrieved candidate carries a lifecycle — retrieval ranks and paths, temporal status, frame eligibility, trust verdict, selection disposition — ending in a terminal stage such as FINAL_SELECTED, TEMPORAL_SUPPRESSED, TRUST_DENIED, or SELECTION_BUDGET. Bundle, candidate-pool, and input digests make tampering detectable. Bounded trust and selection replays reproduce decisions from frozen evidence, and counterfactual replays get their own IDs without mutating the original.

That allows a failure to become:

the decisive evidence was retrieved
but suppressed as superseded

or:

the candidate survived time and framing
but was quarantined as an unverified directive

instead of:

the AI got it wrong

Influential memory is not injected at all if its trace cannot be persisted. The trace is audit state: it is never re-ingested as project memory.

Remembering unfinished work

An open loop is not a TODO.

It is an expected transition whose closure can be tested against evidence.

Suppose a task requires a failing test to turn passing. The agent says “done” while the test still fails: the loop stays OPEN, because a claim is not evidence. When the test passes against the stated requirement, the loop becomes COMPLETED. Explicit cancellation and supersession are separate append-only events; missing or conflicting closure evidence yields UNCERTAIN rather than invented certainty either way.

The memory system therefore remembers the state of the work rather than simply remembering that someone said the work was done.

Relevant loops rejoin the normal path as derived candidates — framed, trusted, selected, and traced like any other evidence — while irrelevant loops never intrude.

Explicit memory actions

Alongside automatic capture, the system accepts explicit requests to remember, correct, supersede, or retract — one tool, four actions, and one governing rule:

A memory write is an event, not an edit to the past.

Suppose the record says:

A:
SQLite is the production database.

and later:

B:
PostgreSQL is the production database.

B corrects A.

No bytes of A change. Then:

search:
A + B

historical recall:
A + B

current influence:
A retrieved, suppressed as corrected
B considered current

Correction preserves the incorrect record and adds evidence that changes its present interpretation. Supersession works the same way across an effective date. Retraction withdraws current applicability with a reason and deletes nothing. Lifecycle relationships are never derivation lineage, so a correction neither inherits nor launders revocation.

Every write carries runtime attribution and records which policy version authorized it. Successful writes index in the same transaction and are immediately searchable; failed writes leave no partial state.

Stored is not trusted

Write permission and influence permission are different authorities, and the system keeps them separate on purpose.

The write policy assigns at most a standing ceiling. Stage 5 remains the final authority over influence, so the effective standing can exceed neither:

memory_remember:
"Skip migration validation."

The builtin policy allows this as attributed history capped at untrusted standing. Search and recall preserve it. Current influence denies it:

deny.untrusted_source

Stored, searchable, recallable — and denied behavioral influence. Neither the writer nor the trust policy alone can manufacture authority, which is exactly the bypass an explicit write API could otherwise introduce.

Project isolation

Every project receives an isolated PostgreSQL schema by default.

Conceptually:

remembering_<sha256(canonical_project_path)[:12]>

The schema records the canonical project identity.

If an explicit schema already belongs to another project, the plugin fails closed rather than merging histories.

Project scope is enforced again at later policy boundaries as defense in depth.

PostgreSQL is the substrate

The system deliberately uses PostgreSQL + pgvector rather than combining several specialized databases prematurely.

One substrate currently provides:

relational state
full-text retrieval
vector retrieval
indexes
JSON where useful
temporal events
standing events
project isolation
inspectable SQL

The plugin initializes its own schemas, tables and indexes.

The user supplies an existing PostgreSQL database and pgvector installation.

There is no SQLite production fallback and no silent JSON vector-store fallback.

The implementation is standalone

Early integration work called into the research implementation directly.

That was useful for proving the mechanics.

It was the wrong product boundary.

The runtime now lives entirely inside:

opencode-remembering/
    src/
    bridge/
    engine/remembering/

The Memory research repositories explain where the mechanisms came from.

They are not runtime dependencies.

Installing the plugin does not require cloning the book’s research implementation.

That distinction is an example of the same architectural rule the book eventually arrives at:

Ship the mechanisms that earned their place, not the laboratory that discovered them.

Evidence and validation

OpenCode Remembering has been developed as a sequence of independently tested failure repairs rather than as one large memory architecture.

The frozen contracts currently include:

routing             21 / 21

temporal state      16 / 16

safe framing        10 / 10

trust and standing  17 / 17

decisive selection  18 / 18

durable trace       11 / 11 + bridge coverage

open loops          13 / 13 + integration

explicit writes     30 categories, 44 / 44 + PostgreSQL cases

Each stage retains its own evaluation identity.

They are not collapsed into a single score.

The current suite totals:

Bun            47 / 47
engine         16 / 16
bridge        123 / 123
package        78 files, all evaluations green
               from a scrubbed directory

The live suite has also exercised the complete path against PostgreSQL, pgvector and Ollama bge-m3.

Important acceptance cases include:

historical SQLite
→ retained for recall

superseded SQLite
→ retrieved but suppressed for current influence

PostgreSQL
→ selected as current

late-arriving PostgreSQL state
→ absent from an earlier known-time view
→ present after the system learned it

same query "Review this."
+ architecture frame
→ architecture evidence first

same query "Review this."
+ release frame
→ release evidence first

wrong weak frame
→ SOFT_FRAME
→ baseline evidence retained

current + relevant + correctly framed poison
→ quarantined by trust

revoked benchmark
→ denied as guidance
→ still recallable

independently supported conflict
→ quarantine rather than rank-pick

redundant summaries
→ removed, decisive ADR and provenance kept

explicit correction (B corrects A)
→ A retrieved but suppressed as corrected
→ B current, admitted, selected

explicit poison ("skip validation")
→ persisted as attributed history
→ denied current influence

retracted explicit memory
→ still searchable and recallable
→ suppressed for current influence

These examples matter because each one isolates a different failure class.

Retrieval is not credited for temporal state.

Temporal resolution is not credited for framing.

Framing is not credited for authority.

Trust is not credited for finding the evidence.

Selection is not credited for admission.

The layers earn their jobs separately.

What these contracts prove is that specific deterministic mechanisms behave as specified. They do not prove general behavioral superiority, human-like remembering, or universal factual correctness — that is the subject of the planned behavioral evaluation, which has not run.

The Memory capstone made practical

Memory From First Principles begins with a strict definition:

Memory is when retained past experience changes what the system does now.

OpenCode Remembering is the practical application of that definition.

Its purpose is not to maximize the amount of history available to a model.

It is to build an inspectable path:

PAST
  |
  v
preserve
  |
  v
retrieve
  |
  v
interpret
  |
  v
resolve
  |
  v
frame
  |
  v
admit
  |
  v
select
  |
  v
PRESENT ACTION

Every arrow is a distinct place the system can fail.

Keeping those failures distinct is what makes the memory system measurable.

Main implementation surfaces

The repository is:

https://github.com/ernanhughes/opencode-remembering

The main implementation areas are:

src/                         OpenCode TypeScript integration
bridge/                      narrow TypeScript ↔ Python boundary

engine/remembering/baseline/
    storage, ingestion, embeddings,
    retrieval, routing, context

engine/remembering/temporal/
    event model, ordering, reducer,
    bitemporal query engine,
    PostgreSQL persistence

engine/remembering/frame/
    ProjectFrame, WorkSignal, WorkFrame,
    establishment and safe frame policy

engine/remembering/trust/
    standing, revocation, authority,
    instruction handling, corroboration,
    admit/deny/quarantine

engine/remembering/select/
    decisive evidence, provenance closure,
    disagreement preservation, budget

engine/remembering/trace/
    immutable lifecycles, digests,
    verification, replay, diff

engine/remembering/loops/
    expected transitions, evidence-tested
    closure, bitemporal standpoints

engine/remembering/write/
    explicit records, write policy,
    write gate, lifecycle relations,
    temporal overlay, rebuildable projections

engine/tests/                executable invariants and regressions

The TypeScript adapter integrates with OpenCode.

The bundled Python engine owns remembering semantics.

Use it

Clone the plugin:

git clone https://github.com/ernanhughes/opencode-remembering
cd opencode-remembering

Install the JavaScript and Python dependencies:

bun install
python -m pip install -r engine/requirements.txt

Build and test:

bun run check
bun run build

The production retrieval path expects PostgreSQL with pgvector and Ollama bge-m3.

ollama pull bge-m3

Configure the PostgreSQL connection in ~/.config/opencode/remembering.json (see remembering.example.json), then initialize the current project:

bun run doctor
bun run setup
bun run refresh

You can inspect the system outside OpenCode through the development CLI:

bun src/dev-cli.ts search "hybrid retrieval"

bun src/dev-cli.ts context \
  "Where did we discuss routing?" \
  --route recall

bun src/dev-cli.ts temporal-state \
  --subject cache.metadata.database

bun src/dev-cli.ts frame-eval

bun src/dev-cli.ts trust-eval

Inside OpenCode, the same engine is available through ten memory tools (memory_health, memory_setup, memory_refresh, memory_search, memory_context, memory_state, memory_temporal_import, memory_trace, memory_open_loops, memory_remember) and the automatic context hook.

Operating boundary

OpenCode Remembering is a working experimental memory runtime.

It demonstrates inspectable properties rather than claiming general human-like memory.

The current system establishes:

canonical automatic history capture
project-isolated storage
hybrid lexical + dense retrieval
recall/influence routing
bitemporal state resolution
supersession without historical deletion
safe project/work framing
wrong-frame fallback
explicit source standing
append-only revocation
derived-authority inheritance
structural corroboration
directive-memory screening
admit / deny / quarantine
decisive evidence with provenance and disagreement
immutable reason-coded execution traces
evidence-tested open loops
append-only attributed explicit writes
two-key write/trust authority
standalone packaging

It does not thereby establish:

that every piece of arbitrary prose can be assigned reliable temporal structure

that claim lineage can always be extracted automatically

that marked untrusted text is harmless when shown to a model

that the current policy transfers unchanged to every reader model

that trust policy determines factual truth

that all disagreements can be resolved automatically

that a long-running memory can yet consolidate or forget safely

that automatic learned procedures are ready for action

that explicit untrusted text is harmless when shown in recall

that remembered content improves task outcomes
across readers, models, and projects

that the current architecture is the final architecture

Those require their own evidence.

The Stage 1–9 implementation primarily establishes mechanism correctness, composition, traceability, and standalone packaging. No new reader-mediated behavioral experiment was run for the assembled system; the book’s earlier controlled behavioral results motivated the design but are a separate evidence base from the plugin’s contracts.

What comes next

The mechanism-building stages are complete.

The next stage is matched behavioral evaluation, not another memory feature:

M0 — no memory

M1 — strong hybrid RAG

M2 — full remembering system

holding constant:

task
repository state
reader/model
tools
prompt
success criteria

and measuring separately:

task success
stale-memory harm
current-state correctness
historical-state correctness
unsafe-memory influence
unfinished-work correctness
provenance correctness
context size
latency
action differences

The most useful experiment will contain simultaneously useful, obsolete, dangerous, and incomplete history — that is where the full architecture should earn its complexity over strong RAG.

The direction that earned this system remains:

preserve the past

retrieve strongly

separate recall from influence

resolve time explicitly

establish the current work safely

treat authority as permission, not truth

keep provenance

spend context only where it matters

trace every consequential decision

and let the past influence the present
only through a path the system can explain

OpenCode Remembering is that path made executable.