The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* Profile-owned SQLite core. The daemon integration supplies authenticated scope and runs this
* synchronous store outside its latency-sensitive thread. No provider calls or command execution.
*/
import { randomUUID } from 'node:crypto'
import { chmodSync, existsSync, lstatSync, mkdirSync } from 'node:fs'
import { basename, dirname, isAbsolute, join } from 'node:path'
import { builtinSqlite } from '../../../cli/src/lib/sqliteBuiltin.js'
import { redact } from '../shared/guard.js'
import { admission, assertSafe, canonical, digest, proposalFingerprint } from './admission.js'
import type { ProjectLocator } from './project.js'
import type { Database } from './database.js'
import { MemoryQueue, PENDING_RETENTION_MS, QUEUE_SCHEMA, TERMINAL_JOB_STATES } from './queue.js'
import { MemoryReceipts, RECEIPT_SCHEMA, type MemoryDeliveryBinding, type PreparedRecall, type RecallReceipt, type ActivityReceiver } from './receipts.js'
import { libraryActivityQuerySchema, type LibraryActivity, type LibraryActivityQuery } from './library.js'
import { MemoryNotebook, NOTEBOOK_SCHEMA, type NotebookInput, type NotebookLease, type NotebookProposal } from './notebook.js'
import type { InferenceTarget } from './queue.js'
import { visibleEvidenceSql } from './visibility.js'
import { sourceRecallText, type SourceRecallSelection } from './recallSources.js'
import { correctionSchema, libraryCommandSchema, libraryQuerySchema, libraryProjectQuerySchema, notebookQuerySchema, summarize, type NotebookQuery, type NotebookIndex, type NotebookSummary, type NotebookDetail, type LibraryProjectQuery, type LibraryProject, type LibraryProjects, type LibraryQuery, type LibraryPage, type LibraryDetail, type MemoryCorrection, type LibraryCommand, type LibraryPreview } from './library.js'
import {
canAccess, conditionsOverlap, conditionsSchema, draftSchema, hasPointer, matches, MemoryError, parse, sourceSchema, topicSchema,
type MemoryAccess, type MemoryDraft, type MemoryRecord, type MemoryScope, type MemoryState, type MemorySupport,
type RecallItem, type RecallPacket, type RecallRequest, type SourceEvent, type TopicDraft, type TopicPage,
} from './types.js'
type Constructor = new (path: string, options?: Record<string, unknown>) => Database
interface OpenOptions { directory: string; profileId: string; now?: () => number }
type OpenResult = { ok: true; store: CodingMemoryStore } | { ok: false; reason: string }
interface Controls { learn: boolean; recall: boolean; generation: number; captureEpoch: number; learnSince: number | null }
export interface MemoryPreferences { learn: boolean; recall: boolean }
interface Compaction { compactedSources: number; deletedSources: number; removedBytes: number }
// v2 distinguishes intact bounded context from completed turns. A v1 reader must
// refuse this store rather than review queued segments as complete conversations.
// Memory records retain their v1 format; the upgrade only adds queue metadata.
const SCHEMA = 2
const EMPTY = (status: RecallPacket['status'] = 'ok'): RecallPacket => ({ status, items: [], text: '', estimatedTokens: 0 })
const STOP_WORDS = new Set(['a', 'an', 'the', 'and', 'or', 'not', 'to', 'of', 'for', 'in', 'on', 'is', 'it', 'with', 'this', 'that', 'please', 'can', 'you', 'we', 'our', 'my'])
export class CodingMemoryStore {
private closed = false
private transactionDepth = 0
readonly learning: MemoryQueue
private readonly receipts: MemoryReceipts
private readonly notebook: MemoryNotebook
private constructor(private readonly db: Database, readonly profileId: string, private readonly now: () => number) {
this.receipts = new MemoryReceipts({ db, profileId, now, transaction: run => this.transaction(run),
recall: (request, access) => this.recall(request, access), read: (id, access) => this.read(id, access),
allowed: (binding, access) => access.profileId === this.profileId && access.includeProfile
&& (binding.projectId === null ? access.projectIds.length === 0
: access.projectIds.length === 1 && access.projectIds[0] === binding.projectId)
&& this.capturePolicy(binding.projectId, binding.engine, binding.sessionId).included,
})
this.learning = new MemoryQueue({ db, profileId, now, transaction: operation => this.transaction(operation),
controls: () => this.controls(), included: projectId => this.included(projectId),
sessionIncluded: (engine, sessionId) => this.sessionPolicy(engine, sessionId).included,
ingest: (event, generation) => this.ingest(event, generation), source: id => {
const source = this.rawSource(id)
return source && this.sourceIncluded(source) ? source : null
},
propose: (draft, access, generation) => this.propose(draft, access, generation),
compact: sourceIds => { this.compactSources(sourceIds) },
})
this.notebook = new MemoryNotebook({ db, profileId, now, transaction: operation => this.transaction(operation),
controls: () => this.controls(), inputs: (scope, facet) => this.notebookInputs(scope, facet),
putTopic: (draft, access, revision, generation) => this.putTopic(draft, access, revision, generation),
})
}
static open(options: OpenOptions): OpenResult {
let db: Database | undefined
try {
if (!/^[A-Za-z0-9_.:-]{1,200}$/.test(options.profileId)) return { ok: false, reason: 'invalid_profile' }
const Database = builtinSqlite() as unknown as Constructor | null
if (!Database) return { ok: false, reason: 'sqlite_unavailable' }
mkdirSync(options.directory, { recursive: true, mode: 0o700 })
const path = join(options.directory, 'memory.sqlite')
if (existsSync(path) && (!lstatSync(path).isFile() || lstatSync(path).isSymbolicLink())) return { ok: false, reason: 'invalid_store_path' }
db = new Database(path)
chmodSync(path, 0o600)
db.exec('PRAGMA busy_timeout = 25; PRAGMA foreign_keys = ON;')
const meta = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'memory_meta'").get()
if (meta) {
const owner = db.prepare("SELECT value FROM memory_meta WHERE key = 'profile'").get()?.value
const version = db.prepare("SELECT value FROM memory_meta WHERE key = 'schema'").get()?.value
if (owner !== options.profileId) throw new MemoryError('profile_mismatch')
if (version !== '1' && version !== String(SCHEMA)) throw new MemoryError('schema_unsupported')
}
// No long-lived WAL containing deleted text. Both ordinary pages and FTS segments are scrubbed.
db.exec('PRAGMA journal_mode = DELETE; PRAGMA synchronous = FULL; PRAGMA secure_delete = ON;')
const store = new CodingMemoryStore(db, options.profileId, options.now ?? Date.now)
store.transaction(() => {
db!.exec(`
CREATE TABLE IF NOT EXISTS memory_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
CREATE TABLE IF NOT EXISTS projects (id TEXT PRIMARY KEY, included INTEGER NOT NULL CHECK(included IN (0,1)));
CREATE TABLE IF NOT EXISTS memory_project_names (
project_id TEXT PRIMARY KEY REFERENCES projects(id) ON DELETE CASCADE,
name TEXT NOT NULL, location TEXT NOT NULL
);
CREATE TABLE IF NOT EXISTS memory_project_policy (
project_id TEXT PRIMARY KEY REFERENCES projects(id), epoch INTEGER NOT NULL, live_from INTEGER NOT NULL
);
CREATE TABLE IF NOT EXISTS memory_session_policy (
engine TEXT NOT NULL, session_id TEXT NOT NULL, included INTEGER NOT NULL,
epoch INTEGER NOT NULL, live_from INTEGER NOT NULL, PRIMARY KEY(engine, session_id)
);
CREATE TABLE IF NOT EXISTS project_locators (
locator_key TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(id)
);
CREATE TABLE IF NOT EXISTS sources (
id TEXT PRIMARY KEY, native_key TEXT UNIQUE NOT NULL, project_id TEXT, digest TEXT NOT NULL, data TEXT NOT NULL
);
CREATE TABLE IF NOT EXISTS source_lifecycle (
source_id TEXT PRIMARY KEY REFERENCES sources(id) ON DELETE CASCADE,
captured_at INTEGER NOT NULL, needs_compaction INTEGER NOT NULL
);
CREATE TABLE IF NOT EXISTS retired_sources (
id_hash TEXT PRIMARY KEY, native_key TEXT UNIQUE NOT NULL, digest TEXT NOT NULL
);
CREATE TABLE IF NOT EXISTS memories (
rowid INTEGER PRIMARY KEY, id TEXT UNIQUE NOT NULL, revision INTEGER NOT NULL,
project_id TEXT, task_id TEXT, branch_id TEXT, scope_key TEXT NOT NULL, conflict_key TEXT NOT NULL,
state TEXT NOT NULL, fingerprint TEXT NOT NULL, data TEXT NOT NULL
);
CREATE INDEX IF NOT EXISTS memories_scope ON memories(project_id, state);
CREATE INDEX IF NOT EXISTS memories_conflicts ON memories(scope_key, conflict_key, state);
CREATE INDEX IF NOT EXISTS memories_conflict_key ON memories(conflict_key, state);
CREATE INDEX IF NOT EXISTS memories_fingerprint ON memories(fingerprint);
CREATE TABLE IF NOT EXISTS revisions (
memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
revision INTEGER NOT NULL, data TEXT NOT NULL, PRIMARY KEY(memory_id, revision)
);
CREATE TABLE IF NOT EXISTS memory_scope_changes (
memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
revision INTEGER NOT NULL, from_scope TEXT NOT NULL, to_scope TEXT NOT NULL,
changed_at INTEGER NOT NULL, PRIMARY KEY(memory_id, revision)
);
CREATE TABLE IF NOT EXISTS evidence (
memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
revision INTEGER NOT NULL, source_id TEXT NOT NULL REFERENCES sources(id), quote TEXT NOT NULL,
PRIMARY KEY(memory_id, revision, source_id, quote)
);
CREATE INDEX IF NOT EXISTS evidence_source ON evidence(source_id);
CREATE TABLE IF NOT EXISTS memory_support (
memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE, fingerprint TEXT NOT NULL,
root_id TEXT NOT NULL, source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
quote TEXT NOT NULL, kind TEXT NOT NULL, session_key TEXT NOT NULL, observed_at INTEGER NOT NULL,
PRIMARY KEY(memory_id, fingerprint, root_id)
);
CREATE INDEX IF NOT EXISTS memory_support_source ON memory_support(source_id);
CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(claim, rationale, cues, tokenize='unicode61');
CREATE TABLE IF NOT EXISTS topics (
id TEXT PRIMARY KEY, revision INTEGER NOT NULL, project_id TEXT, scope_key TEXT NOT NULL, data TEXT
);
CREATE TABLE IF NOT EXISTS topic_dependencies (
topic_id TEXT NOT NULL REFERENCES topics(id) ON DELETE CASCADE,
memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE, revision INTEGER NOT NULL,
PRIMARY KEY(topic_id, memory_id)
);
CREATE INDEX IF NOT EXISTS topic_parents ON topic_dependencies(memory_id);
CREATE TABLE IF NOT EXISTS source_dependencies (
source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE, revision INTEGER NOT NULL,
PRIMARY KEY(source_id, memory_id)
);
CREATE INDEX IF NOT EXISTS source_parents ON source_dependencies(memory_id);
CREATE TABLE IF NOT EXISTS suppressed_sources (key TEXT PRIMARY KEY, at INTEGER NOT NULL);
CREATE TABLE IF NOT EXISTS tombstones (id TEXT PRIMARY KEY, last_revision INTEGER NOT NULL, at INTEGER NOT NULL);
${QUEUE_SCHEMA}
${RECEIPT_SCHEMA}
${NOTEBOOK_SCHEMA}
`)
db!.prepare("INSERT OR IGNORE INTO memory_meta(key, value) VALUES('profile', ?)").run(options.profileId)
db!.prepare("INSERT INTO memory_meta(key, value) VALUES('schema', ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value").run(String(SCHEMA))
db!.prepare("INSERT OR IGNORE INTO memory_meta(key, value) VALUES('controls', ?)").run(JSON.stringify({ learn: false, recall: false, generation: 0, captureEpoch: 0, learnSince: null }))
db!.prepare("INSERT OR IGNORE INTO memory_meta(key,value) VALUES('preferences',?)").run(JSON.stringify({ learn: true, recall: true }))
db!.exec("INSERT OR IGNORE INTO memory_meta(key,value) VALUES('knowledge_epoch','0')")
db!.prepare('INSERT OR IGNORE INTO source_lifecycle(source_id,captured_at,needs_compaction) SELECT id,?,1 FROM sources').run(store.now())
db!.exec("INSERT INTO memory_fts(memory_fts, rank) VALUES('secure-delete', 1)")
})
return { ok: true, store }
} catch (error) {
try { db?.close() } catch { /* Preserve the typed failure; no source text in diagnostics. */ }
return { ok: false, reason: error instanceof MemoryError ? error.code : 'store_unavailable' }
}
}
close(): void { if (!this.closed) { this.db.close(); this.closed = true } }
controls(): Controls {
return JSON.parse(String(this.db.prepare("SELECT value FROM memory_meta WHERE key = 'controls'").get()!.value)) as Controls
}
preferences(): MemoryPreferences {
return JSON.parse(String(this.db.prepare("SELECT value FROM memory_meta WHERE key='preferences'").get()!.value)) as MemoryPreferences
}
/** A settings form cannot overwrite a newer window's acknowledged choice. */
changePreferences(value: MemoryPreferences, expected: MemoryPreferences, enabled = true): MemoryPreferences {
if ([value.learn, value.recall, expected.learn, expected.recall].some(flag => typeof flag !== 'boolean')) throw new MemoryError('invalid_input')
return this.transaction(() => {
const previous = this.preferences()
if (previous.learn !== expected.learn || previous.recall !== expected.recall) throw new MemoryError('revision_conflict')
this.setPreferences(value)
if (!enabled) this.setControls({ learn: false, recall: false })
return this.preferences()
})
}
/** Requested controls survive a temporary experimental/consent/account gate closing. */
setPreferences(value: MemoryPreferences): void {
if (typeof value.learn !== 'boolean' || typeof value.recall !== 'boolean') throw new MemoryError('invalid_input')
this.transaction(() => {
this.db.prepare("UPDATE memory_meta SET value=? WHERE key='preferences'").run(JSON.stringify({ learn: value.learn, recall: value.recall }))
this.setControls(value)
})
}
/** Trusted integration controls, not model-proposable fields. */
setControls(value: { learn: boolean; recall: boolean }): void {
if (typeof value.learn !== 'boolean' || typeof value.recall !== 'boolean') throw new MemoryError('invalid_input')
this.transaction(() => {
const previous = this.controls()
if (previous.learn === value.learn && previous.recall === value.recall) return
this.db.prepare("UPDATE memory_meta SET value = ? WHERE key = 'controls'")
.run(JSON.stringify({ ...value, generation: previous.generation + 1,
captureEpoch: previous.captureEpoch + (previous.learn !== value.learn ? 1 : 0),
learnSince: value.learn ? previous.learn ? previous.learnSince : this.now() : null }))
})
}
registerProject(projectId: string): void {
if (!/^[A-Za-z0-9_.:-]{1,200}$/.test(projectId)) throw new MemoryError('invalid_input')
this.db.prepare('INSERT OR IGNORE INTO projects(id, included) VALUES(?, 1)').run(projectId)
}
projectForLocator(locator: ProjectLocator): string {
const key = this.locatorKey(locator)
return this.transaction(() => {
const existing = this.db.prepare('SELECT project_id FROM project_locators WHERE locator_key = ?').get(key)
const id = existing ? String(existing.project_id) : randomUUID()
if (!existing) {
this.registerProject(id)
this.db.prepare('INSERT INTO project_locators(locator_key, project_id) VALUES(?, ?)').run(key, id)
}
// Owner-facing identity only. Labels and local paths are never added to extraction or recall.
// A worktree uses its common repository directory; an explicitly linked clone keeps the first label.
const location = locator.kind === 'git_common_directory' && basename(locator.path) === '.git' ? dirname(locator.path) : locator.path
this.db.prepare('INSERT OR IGNORE INTO memory_project_names(project_id,name,location) VALUES(?,?,?)')
.run(id, redact(basename(location) || 'Project').slice(0, 160), redact(location))
return id
})
}
/** Explicit host-authorized alias for another clone; never inferred from a matching remote. */
linkProjectLocator(projectId: string, locator: ProjectLocator): void {
const key = this.locatorKey(locator)
this.transaction(() => {
if (!this.db.prepare('SELECT id FROM projects WHERE id = ?').get(projectId)) throw new MemoryError('unknown_project')
const previous = this.db.prepare('SELECT project_id FROM project_locators WHERE locator_key = ?').get(key)
if (previous && previous.project_id !== projectId) throw new MemoryError('project_identity_conflict')
this.db.prepare('INSERT OR IGNORE INTO project_locators(locator_key, project_id) VALUES(?, ?)').run(key, projectId)
})
}
setProjectIncluded(projectId: string, included: boolean): void {
if (typeof included !== 'boolean' || !this.db.prepare('SELECT id FROM projects WHERE id = ?').get(projectId)) throw new MemoryError('unknown_project')
this.transaction(() => {
const previous = this.included(projectId)
// An older writer may have changed privacy without removing receiver activity.
// Reinclusion must not revive ratings from the excluded period.
if (!previous || !included) this.receipts.withholdProject(projectId)
if (previous === included) return
this.db.prepare('UPDATE projects SET included = ? WHERE id = ?').run(included ? 1 : 0, projectId)
this.db.prepare(`INSERT INTO memory_project_policy(project_id,epoch,live_from) VALUES(?,1,?)
ON CONFLICT(project_id) DO UPDATE SET epoch=epoch+1,live_from=excluded.live_from`).run(projectId, this.now())
this.db.exec('UPDATE topics SET data = NULL')
this.notebook.invalidate()
const controls = this.controls()
this.db.prepare("UPDATE memory_meta SET value = ? WHERE key = 'controls'").run(JSON.stringify({ ...controls, generation: controls.generation + 1 }))
this.db.prepare(`UPDATE memory_jobs SET state='cancelled', lease_token=NULL, lease_until=0, source_digest=NULL,
last_error='project_privacy_changed', updated_at=? WHERE project_id=? AND state NOT IN ${TERMINAL_JOB_STATES}`)
.run(this.now(), projectId)
if (!included) this.cancelHiddenSources()
else this.reconcileVisibleConflicts()
})
}
sessionPolicy(engine: string, sessionId: string): { included: boolean; epoch: number; liveFrom: number } {
if (![engine, sessionId].every(value => /^[A-Za-z0-9_.:-]{1,200}$/.test(value))) throw new MemoryError('invalid_input')
const row = this.db.prepare('SELECT included, epoch, live_from FROM memory_session_policy WHERE engine=? AND session_id=?').get(engine, sessionId)
return row ? { included: row.included === 1, epoch: Number(row.epoch), liveFrom: Number(row.live_from) }
: { included: true, epoch: 0, liveFrom: 0 }
}
capturePolicy(projectId: string | null, engine: string, sessionId: string): Controls & { included: boolean; sessionEpoch: number; projectEpoch: number; liveFrom: number; knowledgeEpoch: number } {
const policy = this.sessionPolicy(engine, sessionId)
const project = this.db.prepare('SELECT epoch,live_from FROM memory_project_policy WHERE project_id=?').get(projectId)
return { ...this.controls(), included: this.included(projectId) && policy.included,
knowledgeEpoch: Number(this.db.prepare("SELECT value FROM memory_meta WHERE key='knowledge_epoch'").get()!.value),
sessionEpoch: policy.epoch, projectEpoch: Number(project?.epoch ?? 0), liveFrom: Math.max(policy.liveFrom, Number(project?.live_from ?? 0)) }
}
/** Host-authorized privacy control. Withholds previous knowledge without erasing the native conversation. */
setSessionIncluded(engine: string, sessionId: string, included: boolean): void {
if (typeof included !== 'boolean') throw new MemoryError('invalid_input')
this.transaction(() => {
const previous = this.sessionPolicy(engine, sessionId)
if (!previous.included || !included) this.receipts.withholdSession(engine, sessionId)
if (previous.included === included) return
this.db.prepare(`INSERT INTO memory_session_policy(engine,session_id,included,epoch,live_from) VALUES(?,?,?,?,?)
ON CONFLICT(engine,session_id) DO UPDATE SET included=excluded.included, epoch=excluded.epoch, live_from=excluded.live_from`)
.run(engine, sessionId, included ? 1 : 0, previous.epoch + 1, this.now())
const controls = this.controls()
this.db.prepare("UPDATE memory_meta SET value=? WHERE key='controls'").run(JSON.stringify({ ...controls, generation: controls.generation + 1 }))
this.db.prepare(`UPDATE memory_jobs SET state='cancelled', lease_token=NULL, lease_until=0, source_digest=NULL,
last_error='session_privacy_changed', updated_at=? WHERE stream_id IN
(SELECT id FROM memory_streams WHERE engine=? AND session_id=?) AND state NOT IN ${TERMINAL_JOB_STATES}`)
.run(this.now(), engine, sessionId)
// Derived input can belong to a different stream while retaining this session's source roots.
if (!included) this.cancelHiddenSources()
else this.reconcileVisibleConflicts()
// A derived page may combine several sessions. Rebuild it only from currently visible parents.
this.db.exec('UPDATE topics SET data=NULL')
this.notebook.invalidate()
})
}
ingest(input: SourceEvent, expectedGeneration = this.controls().generation): { disposition: 'created' | 'duplicate' | 'suppressed' | 'retired' } {
return this.ingestSource(input, expectedGeneration)
}
private ingestSource(input: SourceEvent, expectedGeneration: number, userAction = false): { disposition: 'created' | 'duplicate' | 'suppressed' | 'retired' } {
const source = parse(sourceSchema, input)
if (source.profileId !== this.profileId) throw new MemoryError('profile_mismatch')
if (!userAction && !this.controls().learn) throw new MemoryError('learning_off')
if (source.eligibility !== 'coding' || !this.included(source.projectId) || !this.sessionPolicy(source.engine, source.sessionId).included) throw new MemoryError('source_ineligible')
// Native adapters preserve roles. Generated packets may only cite already known source roots.
if (source.role !== 'derived' && (source.rootIds.length !== 1 || source.rootIds[0] !== source.id)) throw new MemoryError('invalid_lineage')
const { text, ...metadata } = source
assertSafe(metadata)
const cleaned: SourceEvent = { ...source, text: redact(text) }
const key = digest([source.engine, source.sessionId, source.nativeEventId])
return this.transaction(() => {
const controls = this.controls()
if (!userAction && !controls.learn) throw new MemoryError('learning_off')
if (controls.generation !== expectedGeneration) throw new MemoryError('generation_changed')
if (!this.included(source.projectId)) throw new MemoryError('source_ineligible')
if (this.isSuppressed(cleaned)) return { disposition: 'suppressed' as const }
const receipt = this.db.prepare('SELECT id_hash,native_key,digest FROM retired_sources WHERE id_hash=? OR native_key=?').get(digest(source.id), key)
if (receipt) {
if (receipt.id_hash !== digest(source.id) || receipt.native_key !== key || receipt.digest !== digest(cleaned)) throw new MemoryError('source_identity_conflict')
return { disposition: 'retired' as const }
}
if (source.role === 'derived') {
const actualRoots = new Set<string>()
for (const parent of source.derivedFrom!) {
const row = this.db.prepare('SELECT data FROM memories WHERE id = ?').get(parent.memoryId)
const record = row ? this.record(row) : null
if (!record || record.revision !== parent.revision || record.state !== 'active' || !this.current(record)
|| !this.evidenceIncluded(record)) throw new MemoryError('invalid_lineage')
if (record.scope.projectId && record.scope.projectId !== source.projectId) throw new MemoryError('evidence_scope')
for (const key of ['taskId', 'branchId'] as const) {
if (record.scope[key] !== undefined && record.scope[key] !== source[key]) throw new MemoryError('evidence_scope')
}
for (const evidence of record.evidence) for (const root of this.rawSource(evidence.sourceEventId)!.rootIds) actualRoots.add(root)
}
if (canonical([...actualRoots].sort()) !== canonical([...new Set(source.rootIds)].sort())) throw new MemoryError('invalid_lineage')
}
const existing = this.db.prepare('SELECT id, digest FROM sources WHERE id = ? OR native_key = ?').get(source.id, key)
if (existing) {
if (existing.id !== source.id || existing.digest !== digest(cleaned)) throw new MemoryError('source_identity_conflict')
return { disposition: 'duplicate' as const }
}
this.db.prepare('INSERT INTO sources(id, native_key, project_id, digest, data) VALUES(?, ?, ?, ?, ?)')
.run(source.id, key, source.projectId, digest(cleaned), JSON.stringify(cleaned))
this.db.prepare('INSERT INTO source_lifecycle(source_id,captured_at,needs_compaction) VALUES(?,?,1)').run(source.id, this.now())
for (const parent of source.derivedFrom ?? []) this.db.prepare('INSERT INTO source_dependencies(source_id, memory_id, revision) VALUES(?, ?, ?)')
.run(source.id, parent.memoryId, parent.revision)
return { disposition: 'created' as const }
})
}
source(id: string, access: MemoryAccess): SourceEvent | null {
const source = this.rawSource(id)
return source && this.sourceIncluded(source) && this.allowed({ profileId: source.profileId, ...(source.projectId ? { projectId: source.projectId } : {}),
...(source.taskId ? { taskId: source.taskId } : {}), ...(source.branchId ? { branchId: source.branchId } : {}) }, access) ? source : null
}
/** No model calls. Completed work retains only evidence; unreviewed raw input expires after a week. */
maintain(): Compaction & { expiredJobs: number } {
return this.transaction(() => {
const expiredJobs = this.learning.expire()
const rows = this.db.prepare(`SELECT l.source_id FROM source_lifecycle l WHERE l.needs_compaction=1
AND (l.captured_at<=? OR EXISTS (SELECT 1 FROM memory_job_sources js JOIN memory_jobs j ON j.id=js.job_id
WHERE js.source_id=l.source_id AND j.state IN ${TERMINAL_JOB_STATES}))
AND NOT EXISTS (SELECT 1 FROM memory_job_sources js JOIN memory_jobs j ON j.id=js.job_id
WHERE js.source_id=l.source_id AND j.state NOT IN ${TERMINAL_JOB_STATES})
ORDER BY l.captured_at LIMIT 512`).all(this.now() - PENDING_RETENTION_MS)
const result = this.compactSources(rows.map(row => String(row.source_id)))
this.learning.pruneMetadata()
this.receipts.prune()
this.notebook.pruneEmpty()
return { ...result, expiredJobs }
})
}
private compactSources(ids: string[]): Compaction {
const result: Compaction = { compactedSources: 0, deletedSources: 0, removedBytes: 0 }
for (const id of new Set(ids)) {
if (this.db.prepare(`SELECT 1 FROM memory_job_sources js JOIN memory_jobs j ON j.id=js.job_id
WHERE js.source_id=? AND j.state NOT IN ${TERMINAL_JOB_STATES} LIMIT 1`).get(id)) continue
const row = this.db.prepare('SELECT * FROM sources WHERE id=?').get(id)
if (!row) continue
const quotes = this.db.prepare('SELECT quote FROM evidence WHERE source_id=? UNION SELECT quote FROM memory_support WHERE source_id=?')
.all(id, id).map(row => String(row.quote))
if (!quotes.length) {
// Content-free receipts preserve idempotency when an old native record is replayed.
this.db.prepare('INSERT OR IGNORE INTO retired_sources(id_hash,native_key,digest) VALUES(?,?,?)').run(digest(id), row.native_key, row.digest)
this.db.prepare('DELETE FROM sources WHERE id=?').run(id)
result.deletedSources++; result.removedBytes += Buffer.byteLength(String(row.data))
} else {
const source = JSON.parse(String(row.data)) as SourceEvent
const text = retainExcerpts(source.text, quotes)
const data = JSON.stringify({ ...source, text, retention: 'evidence_only' })
this.db.prepare('UPDATE sources SET data=? WHERE id=?').run(data, id)
this.db.prepare('UPDATE source_lifecycle SET needs_compaction=0 WHERE source_id=?').run(id)
result.compactedSources++; result.removedBytes += Math.max(0, Buffer.byteLength(String(row.data)) - Buffer.byteLength(data))
}
}
return result
}
propose(input: MemoryDraft, access: MemoryAccess, expectedGeneration = this.controls().generation): { record: MemoryRecord; disposition: 'created' | 'duplicate' } {
const draft = parse(draftSchema, input)
return this.transaction(() => {
this.assertWritable(draft.scope, access, expectedGeneration)
const state = this.validateEvidence(draft)
const fingerprint = proposalFingerprint(draft)
const duplicate = this.db.prepare("SELECT data FROM memories WHERE fingerprint = ? AND state != 'superseded'").get(fingerprint)
if (duplicate) {
let record = this.record(duplicate)
// A fresh public statement can independently support the same meaning. Never return its
// old private evidence to the caller; preserve that revision only in its private history.
if (!this.evidenceIncluded(record)) {
record = { ...record, ...draft, revision: record.revision + 1, state, updatedAt: this.now() }
this.withholdConflicts(record)
this.writeRecord(record)
}
this.recordSupport(record, draft)
return { record, disposition: 'duplicate' as const }
}
const record: MemoryRecord = { ...draft, schemaVersion: 1, id: randomUUID(), revision: 1, state, createdAt: this.now(), updatedAt: this.now() }
this.withholdConflicts(record)
this.writeRecord(record)
this.recordSupport(record, draft)
return { record, disposition: 'created' as const }
})
}
revise(id: string, expectedRevision: number, input: MemoryDraft, access: MemoryAccess,
supersede: Array<{ id: string; revision: number }> = []): MemoryRecord {
return this.reviseRecord(id, expectedRevision, input, access, supersede)
}
/** Host-only explicit form submission. Automatic extraction must use propose/revise instead. */
correctFromUser(id: string, expectedRevision: number, input: Omit<MemoryDraft, 'evidence' | 'evidenceClass'>,
access: MemoryAccess, supersede: Array<{ id: string; revision: number }> = []): MemoryRecord {
return this.transaction(() => {
this.requireRecord(id, expectedRevision, access)
const eventId = randomUUID()
const fields = ['claim', 'rationale', 'futureAction', 'applicability', 'exceptions', 'validity', 'details'] as const
const evidence = fields.filter(field => input[field] !== undefined).map(field => ({
sourceEventId: eventId, quote: canonical(input[field]), paths: [`/${field}`],
}))
const draft = parse(draftSchema, { ...input, evidenceClass: 'user_stated', evidence })
this.assertWritable(draft.scope, access, this.controls().generation, true)
this.ingestSource({ id: eventId, profileId: this.profileId, projectId: draft.scope.projectId ?? null,
...(draft.scope.taskId ? { taskId: draft.scope.taskId } : {}), ...(draft.scope.branchId ? { branchId: draft.scope.branchId } : {}),
engine: 'harness_viewer', sessionId: `correction:${id}`, nativeEventId: eventId, role: 'user',
eligibility: 'coding', observedAt: this.now(), rootIds: [eventId], text: canonical(input),
}, this.controls().generation, true)
return this.reviseRecord(id, expectedRevision, draft, access, supersede, true)
})
}
private reviseRecord(id: string, expectedRevision: number, input: MemoryDraft, access: MemoryAccess,
supersede: Array<{ id: string; revision: number }>, userAction = false): MemoryRecord {
const draft = parse(draftSchema, input)
return this.transaction(() => {
const previous = this.requireRecord(id, expectedRevision, access)
this.assertWritable(draft.scope, access, this.controls().generation, userAction)
// A correction is backed by a new actual user event, never an old quotation or an agent claim.
if (!draft.evidence.some(e => this.rawSource(e.sourceEventId)?.role === 'user'
&& !previous.evidence.some(old => old.sourceEventId === e.sourceEventId))) throw new MemoryError('correction_requires_user_evidence')
const record: MemoryRecord = { ...draft, schemaVersion: 1, id, revision: previous.revision + 1,
state: this.validateEvidence(draft), createdAt: previous.createdAt, updatedAt: this.now() }
if (supersede.length > 32 || new Set(supersede.map(peer => peer.id)).size !== supersede.length) throw new MemoryError('invalid_resolution')
const peers = supersede.map(peer => this.requireRecord(peer.id, peer.revision, access))
for (const peer of peers) {
if (peer.id === id || canonical(peer.scope) !== canonical(record.scope) || peer.conflictKey !== record.conflictKey
|| !['active', 'needs_verification'].includes(peer.state) || !conditionsOverlap(peer.applicability, record.applicability)) throw new MemoryError('invalid_resolution')
}
for (const peer of peers) this.writeRecord({ ...peer, revision: peer.revision + 1, state: 'superseded', updatedAt: this.now() })
this.withholdConflicts(record)
this.writeRecord(record)
this.recordSupport(record, draft)
this.invalidateLearning(previous)
return record
})
}
read(id: string, access: MemoryAccess): MemoryRecord | null {
const row = this.db.prepare('SELECT data FROM memories WHERE id = ?').get(id)
if (!row) return null
const record = this.record(row)
return this.allowed(record.scope, access) && this.evidenceIncluded(record) ? record : null
}
history(id: string, access: MemoryAccess): MemoryRecord[] {
if (!this.read(id, access)) return []
return this.db.prepare('SELECT data FROM revisions WHERE memory_id = ? ORDER BY revision').all(id)
.map(row => this.record(row)).filter(record => this.allowed(record.scope, access) && this.evidenceIncluded(record))
}
support(id: string, access: MemoryAccess): MemorySupport | null {
const record = this.read(id, access)
if (!record) return null
const rows = this.db.prepare('SELECT * FROM memory_support WHERE memory_id=? AND fingerprint=?')
.all(id, proposalFingerprint(asDraft(record))).filter(row => {
const source = this.rawSource(String(row.source_id))
return source && this.sourceIncluded(source)
})
return { independentUserStatements: rows.filter(row => row.kind === 'user_statement').length,
verifiedObservations: rows.filter(row => row.kind === 'verified_observation').length,
distinctSessions: new Set(rows.map(row => row.session_key)).size,
lastObservedAt: rows.length ? Math.max(...rows.map(row => Number(row.observed_at))) : null }
}
list(access: MemoryAccess, limit = 100): MemoryRecord[] {
if (access.profileId !== this.profileId) return []
const filter = this.scopeFilter(access)
return this.db.prepare(`SELECT m.data FROM memories m WHERE ${filter.sql} AND ${visibleEvidenceSql()} ORDER BY m.rowid DESC LIMIT ?`)
.all(...filter.params, bounded(limit, 100, 1, 200)).map(row => this.record(row)).filter(record => this.allowed(record.scope, access) && this.evidenceIncluded(record))
}
/** A separately authorized owner view, including task/branch scopes. Never use for an agent read. */
libraryPage(owner: string, input: LibraryQuery = {}): LibraryPage {
this.requireOwner(owner)
const query = parse(libraryQuerySchema, input)
if (query.projectId && query.scope === 'personal') throw new MemoryError('invalid_input')
const { cursor, limit = 25, ...filters } = query
const version = this.libraryVersion()
const filterKey = digest(filters)
let before = Number.MAX_SAFE_INTEGER
if (cursor) {
try {
const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as Record<string, unknown>
if (parsed.owner !== this.profileId || parsed.filter !== filterKey || !Number.isSafeInteger(parsed.before)
|| Number(parsed.before) <= 0) throw new MemoryError('invalid_cursor')
if (parsed.generation !== version.generation || parsed.knowledge !== version.knowledge || parsed.preferences !== version.preferences) throw new MemoryError('page_changed')
before = Number(parsed.before)
} catch (error) { throw error instanceof MemoryError ? error : new MemoryError('invalid_cursor') }
}
const where = ['m.rowid < ?', '(m.project_id IS NULL OR EXISTS (SELECT 1 FROM projects p WHERE p.id=m.project_id AND p.included=1))', visibleEvidenceSql()]
const params: unknown[] = [before]
if (query.scope === 'personal') where.push('m.project_id IS NULL')
if (query.scope === 'project') where.push('m.project_id IS NOT NULL')
if (query.projectId) { where.push('m.project_id=?'); params.push(query.projectId) }
if (query.topicId) {
where.push(`EXISTS (SELECT 1 FROM memory_notebook_jobs j WHERE j.id=? AND j.scope_key=m.scope_key AND j.facet=json_extract(m.data,'$.facet'))`)
params.push(query.topicId)
}
if (query.state) { where.push('m.state=?'); params.push(query.state) }
const rows = this.db.prepare(`SELECT m.rowid,m.data FROM memories m WHERE ${where.join(' AND ')} ORDER BY m.rowid DESC LIMIT ?`)
.all(...params, limit + 1)
const page = rows.slice(0, limit)
return { items: page.map(row => summarize(this.record(row))), version,
nextCursor: rows.length > limit ? Buffer.from(JSON.stringify({ owner: this.profileId, filter: filterKey,
before: Number(page.at(-1)!.rowid), ...version })).toString('base64url') : null }
}
/** Exact retained quotations live in record.evidence; never expose unrelated source transcript text. */
libraryDetail(owner: string, id: string): LibraryDetail | null {
this.requireOwner(owner)
const access = this.ownerRecordAccess(id)
if (!access) return null
const record = this.read(id, access)
if (!record) return null
const sources = [...new Set(record.evidence.map(evidence => evidence.sourceEventId))].map(id => this.rawSource(id)!)
.map(({ id, engine, sessionId, role, observedAt }) => ({ id, engine, sessionId, role, observedAt }))
const scopeChanges: LibraryDetail['scopeChanges'] = this.db.prepare(`SELECT * FROM memory_scope_changes WHERE memory_id=?
ORDER BY revision DESC LIMIT 20`).all(id).map(row => ({ revision: Number(row.revision),
from: JSON.parse(String(row.from_scope)), to: JSON.parse(String(row.to_scope)), changedAt: Number(row.changed_at), actor: 'owner' }))
return { record, sources, support: this.support(id, access), scopeChanges,
project: record.scope.projectId ? this.projectLabel(record.scope.projectId) : null,
recalls: this.receipts.forMemory(record.id, record.revision).map(({ projectId, ...recall }) => ({ ...recall,
project: projectId ? this.projectLabel(projectId) : null, canFeedback: record.state === 'active' && this.current(record) })) }
}
libraryProjects(owner: string, input: LibraryProjectQuery = {}): LibraryProjects {
this.requireOwner(owner)
const query = parse(libraryProjectQuerySchema, input)
const limit = query.limit ?? 20
// Privacy applies before the bounded page. Names/paths are literal search text, never SQL patterns.
const rows = this.db.prepare(`SELECT p.rowid,p.id,n.name,n.location FROM projects p
LEFT JOIN memory_project_names n ON n.project_id=p.id WHERE p.included=1 AND p.rowid<?
AND instr(lower(COALESCE(n.name,p.id) || ' ' || COALESCE(n.location,'')),lower(?))>0
ORDER BY p.rowid DESC LIMIT ?`).all(query.before ?? Number.MAX_SAFE_INTEGER, query.search ?? '', limit + 1)
return { items: rows.slice(0, limit).map(row => this.projectLabel(String(row.id))),
nextBefore: rows.length > limit ? Number(rows[limit - 1].rowid) : null }
}
/** Host-supplied open sessions; only the verified owner may inspect their latest selections. */
libraryActivity(owner: string, receivers: ActivityReceiver[], input: LibraryActivityQuery = {}): LibraryActivity {
this.requireOwner(owner)
const query = parse(libraryActivityQuerySchema, input)
return this.transaction(() => {
const sessions = this.receipts.activity(receivers).map(({ projectId, ...row }) => ({ ...row,
project: projectId ? this.projectLabel(projectId) : null }))
const selectedAgentId = query.agentId ?? sessions[0]?.agentId ?? null
const selection = sessions.find(row => row.agentId === selectedAgentId)
const items: LibraryActivity['items'] = []
for (const item of selection?.receiptId ? this.receipts.activityItems(selection.receiptId) : []) {
const access = this.ownerRecordAccess(item.id)
const record = access && this.read(item.id, access)
if (!record || record.revision !== item.revision || record.state !== 'active' || !this.current(record)) continue
const recall = this.receipts.forMemory(item.id, item.revision, selection!.receiptId!)[0]
if (!recall) continue
const { projectId, ...use } = recall
items.push({ record: { ...summarize(record), applicability: record.applicability,
rationale: record.rationale, futureAction: record.futureAction, exceptions: record.exceptions },
recall: { ...use, canFeedback: true, project: projectId ? this.projectLabel(projectId) : null } })
}
return { sessions, selectedAgentId, items, version: this.libraryVersion() }
})
}
private projectLabel(id: string): LibraryProject {
const row = this.db.prepare('SELECT name,location FROM memory_project_names WHERE project_id=?').get(id)
return { id, name: row ? String(row.name) : `Project ${id}`, location: row ? String(row.location) : null }
}
/** Restrict applicability through the person-only preview flow; this is not new truth evidence. */
private libraryNarrow(owner: string, id: string, revision: number, projectId: string): LibraryPreview['effects'] {
this.requireOwner(owner)
return this.transaction(() => {
const access = this.ownerRecordAccess(id)
if (!access) throw new MemoryError('not_found')
const previous = this.requireRecord(id, revision, access)
if (previous.scope.projectId) throw new MemoryError('scope_narrowing_only')
if (!['active', 'tentative', 'needs_verification'].includes(previous.state)) throw new MemoryError('memory_not_active')
if (this.db.prepare('SELECT included FROM projects WHERE id=?').get(projectId)?.included !== 1) throw new MemoryError('project_unavailable')
const scope = { ...previous.scope, projectId }
const draft = { ...asDraft(previous), scope }
this.assertWritable(scope, { ...access, projectIds: [projectId] }, this.controls().generation, true)
const admitted = this.validateEvidence(draft)
const record: MemoryRecord = { ...previous, scope, revision: previous.revision + 1, updatedAt: this.now(),
state: previous.state === 'active' ? admitted : previous.state }
const conflicts = this.withholdConflicts(record)
this.writeRecord(record)
// The claim is unchanged. Carry every existing independent root to the restricted scope,
// including corroboration beyond record.evidence; narrowing adds no new confirmation.
this.db.prepare(`INSERT OR IGNORE INTO memory_support
(memory_id,fingerprint,root_id,source_id,quote,kind,session_key,observed_at)
SELECT memory_id,?,root_id,source_id,quote,kind,session_key,observed_at FROM memory_support
WHERE memory_id=? AND fingerprint=?`).run(proposalFingerprint(draft), id, proposalFingerprint(asDraft(previous)))
this.invalidateLearning(previous)
const scopeChange = { revision: record.revision, from: previous.scope, to: scope, changedAt: this.now(), actor: 'owner' as const }
this.db.prepare('INSERT INTO memory_scope_changes VALUES(?,?,?,?,?)')
.run(id, record.revision, canonical(previous.scope), canonical(scope), scopeChange.changedAt)
return { record: summarize(record), scopeChange, project: this.projectLabel(projectId), conflicts: conflicts.map(summarize) }
})
}
libraryCorrect(owner: string, id: string, revision: number, input: MemoryCorrection,
supersede: Array<{ id: string; revision: number }> = []): MemoryRecord {
this.requireOwner(owner)
const fields = parse(correctionSchema, input)
const access = this.ownerRecordAccess(id)
if (!access) throw new MemoryError('not_found')
const previous = this.requireRecord(id, revision, access)
// A form edit is a user statement, not a test/benchmark result. Keep measured findings on the
// evidence path; an owner may forget them, but cannot accidentally preserve a verification badge.
if (previous.assertionType === 'verified_finding' || previous.details?.experiment?.runs) throw new MemoryError('verification_required')
// Only submitted fields become a fresh user statement. In particular, do not silently promote
// old inferred detail objects that the correction form did not include in its preview.
const { evidence: _evidence, evidenceClass: _class, details: _details, ...draft } = asDraft(previous)
return this.correctFromUser(id, revision, { ...draft, ...fields }, access, supersede)
}
libraryForget(owner: string, id: string, revision: number): ReturnType<CodingMemoryStore['forget']> {
this.requireOwner(owner)
const access = this.ownerRecordAccess(id)
if (!access) throw new MemoryError('not_found')
return this.forget(id, revision, access)
}
libraryPreview(owner: string, input: LibraryCommand): LibraryPreview {
this.requireOwner(owner)
const command = parse(libraryCommandSchema, input)
const rollback = {}
let preview: LibraryPreview | undefined
try {
this.transaction(() => {
const version = this.libraryVersion()
const effects = this.runLibraryCommand(owner, command, false)
if (Buffer.byteLength(JSON.stringify(effects), 'utf8') > 256_000) throw new MemoryError('preview_too_large')
preview = { version, command, effects }
throw rollback
})
} catch (error) { if (error !== rollback) throw error }
return preview!
}
/** The transport spends a person-only capability, then commits exactly the previewed snapshot. */
libraryApply(owner: string, input: LibraryCommand, expected: LibraryPage['version'], enabled: boolean): LibraryPreview['effects'] {
this.requireOwner(owner)
const command = parse(libraryCommandSchema, input)
return this.transaction(() => {
if (canonical(expected) !== canonical(this.libraryVersion())) throw new MemoryError('preview_changed')
return this.runLibraryCommand(owner, command, enabled)
})
}
private runLibraryCommand(owner: string, command: LibraryCommand, enabled: boolean): LibraryPreview['effects'] {
switch (command.kind) {
case 'correct': return { record: summarize(this.libraryCorrect(owner, command.id, command.revision, command.fields, command.supersede)) }
case 'forget': return this.libraryForget(owner, command.id, command.revision)
case 'narrow': return this.libraryNarrow(owner, command.id, command.revision, command.projectId)
case 'feedback': {
const access = this.ownerRecordAccess(command.id)
if (!access) throw new MemoryError('not_found')
const record = this.requireRecord(command.id, command.revision, access)
if (record.state !== 'active' || !this.current(record)) throw new MemoryError('recall_unavailable')
return { feedback: this.receipts.feedback(record.id, record.revision, command.receiptId, command.value, command.expected) }
}
case 'configure': return { preferences: this.changePreferences(command.preferences, command.expected, enabled) }
}
}
private requireOwner(owner: string): void {
if (owner !== this.profileId) throw new MemoryError('scope_denied')
}
private libraryVersion(): LibraryPage['version'] {
return { generation: this.controls().generation,
knowledge: Number(this.db.prepare("SELECT value FROM memory_meta WHERE key='knowledge_epoch'").get()!.value),
preferences: digest(this.preferences()) }
}
private ownerRecordAccess(id: string): MemoryAccess | null {
if (typeof id !== 'string' || !/^[A-Za-z0-9_.:-]{1,200}$/.test(id)) throw new MemoryError('invalid_input')
const row = this.db.prepare('SELECT data FROM memories WHERE id=?').get(id)
if (!row) return null
const { profileId, projectId, taskId, branchId } = this.record(row).scope
return { profileId, projectIds: projectId ? [projectId] : [], includeProfile: true, taskId, branchId }
}
recall(request: RecallRequest, access: MemoryAccess): RecallPacket {
if (access.profileId !== this.profileId) return EMPTY('denied')
if (!this.controls().recall) return EMPTY('off')
if (typeof request.query !== 'string') throw new MemoryError('invalid_input')
if (request.format !== undefined && !['summary', 'source_excerpts'].includes(request.format)) throw new MemoryError('invalid_input')
const actual = parse(conditionsSchema, request.conditions ?? {})
const excluded = request.excludeIds ?? []
if (!Array.isArray(excluded) || excluded.length > 1_000 || excluded.some(id => typeof id !== 'string' || id.length > 200)) throw new MemoryError('invalid_input')
const terms = [...new Set(request.query.slice(0, 4_000).normalize('NFKC').toLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? [])]
.filter(word => word.length >= 2 && !STOP_WORDS.has(word)).slice(0, 16)
if (!terms.length) return EMPTY()
const filter = this.scopeFilter(access)
const now = this.now()
const specific = this.scopeFilter(access, 'specific')
// Quoted tokens contain no FTS operators. Scope/state filtering happens before candidate limiting.
// Drive the join from FTS once. A scope-index-first plan reruns MATCH for every project row
// (measured at ~160 ms for 10k rows); the fixed join order still filters access before LIMIT.
const rows = this.db.prepare(`WITH context(actual) AS (VALUES (?))
SELECT m.id,m.revision,m.data,bm25(memory_fts, 4, 1, 3) AS lexical_rank FROM memory_fts CROSS JOIN memories m ON m.rowid = memory_fts.rowid
WHERE memory_fts MATCH ? AND m.state = 'active' AND ${filter.sql}
AND ${visibleEvidenceSql()}
AND ${applicabilitySql("json_extract(m.data, '$.applicability')")}
AND NOT EXISTS (SELECT 1 FROM json_each(m.data, '$.exceptions') exception
WHERE ${applicabilitySql("json_extract(exception.value, '$.when')")})
AND (json_extract(m.data, '$.validity.validFrom') IS NULL OR json_extract(m.data, '$.validity.validFrom') <= ?)
AND (json_extract(m.data, '$.validity.validUntil') IS NULL OR json_extract(m.data, '$.validity.validUntil') > ?)
AND NOT EXISTS (SELECT 1 FROM memories specific WHERE specific.conflict_key=m.conflict_key
AND specific.state IN ('active','needs_verification') AND ${specific.sql}
AND (m.project_id IS NULL OR m.project_id=specific.project_id)
AND (m.task_id IS NULL OR m.task_id=specific.task_id)
AND (m.branch_id IS NULL OR m.branch_id=specific.branch_id)
AND ((m.project_id IS NULL AND specific.project_id IS NOT NULL)
OR (m.task_id IS NULL AND specific.task_id IS NOT NULL) OR (m.branch_id IS NULL AND specific.branch_id IS NOT NULL))
AND ${visibleEvidenceSql('specific')}
AND ${applicabilitySql("json_extract(specific.data, '$.applicability')")}
AND NOT EXISTS (SELECT 1 FROM json_each(specific.data, '$.exceptions') specific_exception
WHERE ${applicabilitySql("json_extract(specific_exception.value, '$.when')")})
AND (json_extract(specific.data,'$.validity.validFrom') IS NULL OR json_extract(specific.data,'$.validity.validFrom')<=?)
AND (json_extract(specific.data,'$.validity.validUntil') IS NULL OR json_extract(specific.data,'$.validity.validUntil')>?))
${excluded.length ? `AND m.id NOT IN (${excluded.map(() => '?').join(',')})` : ''}
ORDER BY bm25(memory_fts, 4, 1, 3), m.rowid DESC LIMIT 120`)
.all(JSON.stringify(actual), terms.map(term => `"${term}"`).join(' OR '), ...filter.params, now, now, ...specific.params, now, now, ...excluded)
const utility = this.receipts.usefulness(rows.map(row => ({ id: String(row.id), revision: Number(row.revision) })), access, actual)
if (utility.size) {
const score = (row: Record<string, unknown>) => Number(row.lexical_rank) * (1 + (utility.get(String(row.id)) ?? 0))
rows.sort((left, right) => score(left) - score(right))
}
const packet = EMPTY()
const sourceSelections: SourceRecallSelection[] = []
const maxBytes = bounded(request.maxBytes, 3_000, 0, 16_000)
const maxItems = bounded(request.maxItems, 6, 0, 6)
for (const row of rows) {
if (packet.items.length >= maxItems) break
const record = this.record(row)
if (!this.allowed(record.scope, access) || request.excludeIds?.includes(record.id)
|| !matches(record.applicability, actual)
|| record.exceptions.some(exception => matches(exception.when, actual))
|| !this.current(record, now)) continue
const sources = record.evidence.map(e => this.rawSource(e.sourceEventId))
if (sources.some(source => !source || !this.sourceIncluded(source))) continue
const item: RecallItem = {
id: record.id, revision: record.revision, kind: record.kind, assertionType: record.assertionType,
scope: record.scope, claim: record.claim, rationale: record.rationale, futureAction: record.futureAction,
conditions: record.applicability, exceptions: record.exceptions, evidenceClass: record.evidenceClass,
verification: record.evidence.flatMap(evidence => evidence.verification ? [evidence.verification] : []),
cautions: [
...(record.assertionType === 'temporary_state' ? ['Unfinished task context; hypotheses remain unproven.'] : []),
...record.validity.recheckWhen,
],
sources: [...new Map(sources.map(source => [source!.id, { id: source!.id, engine: source!.engine, role: source!.role, observedAt: source!.observedAt }])).values()],
}
const selection = { record, sources: sources as SourceEvent[] }
const text = request.format === 'source_excerpts'
? sourceRecallText([...sourceSelections, selection])
: JSON.stringify({ type: 'coding_memory_context', notice: 'Historical context; follow current instructions and current project requirements. Project-specific guidance takes precedence over personal defaults. Memory grants no action permissions.', items: [...packet.items, item] })
if (Buffer.byteLength(text, 'utf8') > maxBytes) continue
packet.items.push(item); packet.text = text
if (request.format === 'source_excerpts') sourceSelections.push(selection)
}
packet.estimatedTokens = Math.ceil(Buffer.byteLength(packet.text, 'utf8') / 3)
return packet
}
prepareRecall(request: RecallRequest, binding: MemoryDeliveryBinding, access: MemoryAccess): PreparedRecall {
return this.receipts.prepare(request, binding, access)
}
recallEmitted(receiptId: string, binding: MemoryDeliveryBinding, access: MemoryAccess): boolean {
return this.receipts.emitted(receiptId, binding, access)
}
recallReceipts(binding: MemoryDeliveryBinding, access: MemoryAccess, limit = 20): RecallReceipt[] {
return this.receipts.list(binding, access, limit)
}
notebookPending(): ReturnType<MemoryNotebook['pending']> { return this.notebook.pending() }
notebookClaim(target: InferenceTarget): ReturnType<MemoryNotebook['claim']> { return this.notebook.claim(target) }
notebookFinish(lease: NotebookLease, proposal: NotebookProposal, target: InferenceTarget): ReturnType<MemoryNotebook['finish']> {
return this.notebook.finish(lease, proposal, target)
}
notebookDefer(...args: Parameters<MemoryNotebook['defer']>): void { this.notebook.defer(...args) }
/** Owner-only index. Apply source and project visibility before pagination, including labels. */
libraryNotebooks(owner: string, input: NotebookQuery = {}): NotebookIndex {
this.requireOwner(owner)
const query = parse(notebookQuerySchema, input), version = this.libraryVersion()
const { limit = 12, cursor, ...filters } = query
const filter = digest(['notebooks', filters])
let before = Number.MAX_SAFE_INTEGER
if (cursor) {
try {
const value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as Record<string, unknown>
if (value.owner !== owner || value.filter !== filter || !Number.isSafeInteger(value.before) || Number(value.before) <= 0) throw new MemoryError('invalid_cursor')
if (canonical(value.version) !== canonical(version)) throw new MemoryError('page_changed')
before = Number(value.before)
} catch (error) { throw error instanceof MemoryError ? error : new MemoryError('invalid_cursor') }
}
const rows = this.db.prepare(`SELECT j.rowid,j.* FROM memory_notebook_jobs j
JOIN projects p ON p.id=j.project_id AND p.included=1 WHERE j.rowid<?
${query.projectId ? 'AND j.project_id=?' : ''}
AND EXISTS (SELECT 1 FROM memories m WHERE m.scope_key=j.scope_key AND json_extract(m.data,'$.facet')=j.facet
AND m.state IN ('active','tentative','needs_verification') AND ${visibleEvidenceSql()})
ORDER BY j.rowid DESC LIMIT ?`).all(before, ...(query.projectId ? [query.projectId] : []), limit + 1)
const page = rows.slice(0, limit)
return { items: page.map(row => this.notebookSummary(row)), version,
nextCursor: rows.length > limit ? Buffer.from(JSON.stringify({ owner, filter, version, before: Number(page.at(-1)!.rowid) })).toString('base64url') : null }
}
libraryNotebook(owner: string, id: string): NotebookDetail | null {
this.requireOwner(owner)
const row = this.db.prepare(`SELECT j.* FROM memory_notebook_jobs j JOIN projects p ON p.id=j.project_id AND p.included=1
WHERE j.id=? AND EXISTS (SELECT 1 FROM memories m WHERE m.scope_key=j.scope_key AND json_extract(m.data,'$.facet')=j.facet
AND m.state IN ('active','tentative','needs_verification') AND ${visibleEvidenceSql()})`).get(id)
if (!row) return null
const summary = this.notebookSummary(row), access = this.notebookAccess(summary.scope)
const explanation = this.topic(id, access)
const ids = new Set(explanation?.statements.flatMap(statement => statement.supports.map(support => support.memoryId)) ?? [])
return { summary, explanation, supporting: [...ids].map(id => summarize(this.read(id, access)!)),
memories: this.libraryPage(owner, { topicId: id, limit: 20 }) }
}
private notebookAccess(scope: MemoryScope): MemoryAccess {
return { profileId: this.profileId, projectIds: scope.projectId ? [scope.projectId] : [], includeProfile: false,
...(scope.taskId ? { taskId: scope.taskId } : {}), ...(scope.branchId ? { branchId: scope.branchId } : {}) }
}
private notebookSummary(row: Record<string, unknown>): NotebookSummary {
const scope = JSON.parse(String(row.scope_key)) as MemoryScope
const input = this.notebookInputs(scope, String(row.facet))
const page = this.topic(String(row.id), this.notebookAccess(scope))
return { id: String(row.id), title: String(row.facet).replace(/[_.:-]+/g, ' ').replace(/^./, letter => letter.toUpperCase()).slice(0, 120),
scope, project: this.projectLabel(scope.projectId!),
state: row.state === 'ready' && !page ? 'queued' : row.state as NotebookSummary['state'], updatedAt: page?.updatedAt ?? null,
activeRecords: input.total, unresolvedRecords: input.unresolved,
supportingRecords: new Set(page?.statements.flatMap(statement => statement.supports.map(support => support.memoryId)) ?? []).size }
}
private notebookInputs(scope: MemoryScope, facet: string): NotebookInput {
const empty: NotebookInput = { records: [], total: 0, unresolved: 0, nextChangeAt: null }
if (scope.profileId !== this.profileId || !scope.projectId || !this.included(scope.projectId)) return empty
const now = this.now(), params = [canonical(scope), facet]
const common = `m.scope_key=? AND json_extract(m.data,'$.facet')=? AND ${visibleEvidenceSql()}`
const current = `(json_extract(m.data,'$.validity.validFrom') IS NULL OR json_extract(m.data,'$.validity.validFrom')<=?)
AND (json_extract(m.data,'$.validity.validUntil') IS NULL OR json_extract(m.data,'$.validity.validUntil')>?)`
const counts = this.db.prepare(`SELECT
COALESCE(SUM(CASE WHEN m.state='active' THEN 1 ELSE 0 END),0) AS total,
COALESCE(SUM(CASE WHEN m.state IN ('tentative','needs_verification') THEN 1 ELSE 0 END),0) AS unresolved
FROM memories m WHERE ${common} AND ${current}`).get(...params, now, now)!
const boundary = this.db.prepare(`SELECT MIN(at) AS at FROM (
SELECT json_extract(m.data,'$.validity.validFrom') AS at FROM memories m WHERE ${common}
AND m.state IN ('active','tentative','needs_verification') AND json_extract(m.data,'$.validity.validFrom')>?
UNION ALL SELECT json_extract(m.data,'$.validity.validUntil') AS at FROM memories m WHERE ${common}
AND m.state IN ('active','tentative','needs_verification') AND json_extract(m.data,'$.validity.validUntil')>?)`)
.get(...params, now, ...params, now)!.at
const rows = this.db.prepare(`SELECT m.data FROM memories m WHERE ${common} AND m.state='active' AND ${current}
ORDER BY json_extract(m.data,'$.updatedAt') DESC,m.rowid DESC LIMIT 24`).all(...params, now, now)
let bytes = 0
const records: MemoryRecord[] = []
for (const row of rows) {
const size = Buffer.byteLength(String(row.data))
if (bytes + size > 48_000) continue
records.push(this.record(row)); bytes += size
}
return { records, total: Number(counts.total), unresolved: Number(counts.unresolved),
nextChangeAt: boundary == null ? null : Number(boundary) }
}
putTopic(input: TopicDraft, access: MemoryAccess, expectedRevision = 0, expectedGeneration = this.controls().generation): TopicPage {
const draft = parse(topicSchema, input)
assertSafe(draft)
return this.transaction(() => {
this.assertWritable(draft.scope, access, expectedGeneration)
const dependencies = new Map<string, number>()
for (const statement of draft.statements) for (const support of statement.supports) {
const parent = this.read(support.memoryId, access)
if (!parent || parent.state !== 'active' || parent.revision !== support.revision || !this.current(parent)) throw new MemoryError('stale_dependency')
for (const key of ['profileId', 'projectId', 'taskId', 'branchId'] as const) {
if (parent.scope[key] !== undefined && parent.scope[key] !== draft.scope[key]) throw new MemoryError('dependency_scope')
}
if (support.paths.some(path => !hasPointer(parent, path))) throw new MemoryError('evidence_path')
dependencies.set(parent.id, parent.revision)
}
const previous = this.db.prepare('SELECT revision, scope_key FROM topics WHERE id = ?').get(draft.id)
if (previous && !this.allowed(JSON.parse(String(previous.scope_key)) as MemoryScope, access)) throw new MemoryError('not_found')
if (Number(previous?.revision ?? 0) !== expectedRevision) throw new MemoryError('revision_conflict')
const page: TopicPage = { ...draft, revision: Number(previous?.revision ?? 0) + 1, updatedAt: this.now(),
statements: draft.statements.map(statement => ({ ...statement,
constraints: statement.supports.map(support => {
const parent = this.read(support.memoryId, access)!
return { memoryId: parent.id, applicability: parent.applicability, exceptions: parent.exceptions, validity: parent.validity }
}),
})) }
this.db.prepare('INSERT INTO topics(id, revision, project_id, scope_key, data) VALUES(?, ?, ?, ?, ?) ON CONFLICT(id) DO UPDATE SET revision=excluded.revision, project_id=excluded.project_id, scope_key=excluded.scope_key, data=excluded.data')
.run(page.id, page.revision, page.scope.projectId ?? null, canonical(page.scope), JSON.stringify(page))
this.db.prepare('DELETE FROM topic_dependencies WHERE topic_id = ?').run(page.id)
for (const [memoryId, revision] of dependencies) this.db.prepare('INSERT INTO topic_dependencies(topic_id, memory_id, revision) VALUES(?, ?, ?)').run(page.id, memoryId, revision)
this.bumpKnowledgeEpoch()
return page
})
}
topic(id: string, access: MemoryAccess): TopicPage | null {
const notebook = this.db.prepare('SELECT state,available_at FROM memory_notebook_jobs WHERE id=?').get(id)
if (notebook && (notebook.state !== 'ready' || (Number(notebook.available_at) > 0 && Number(notebook.available_at) <= this.now()))) return null
const row = this.db.prepare('SELECT data FROM topics WHERE id = ?').get(id)
if (!row || row.data === null) return null
const page = JSON.parse(String(row.data)) as TopicPage
if (!this.allowed(page.scope, access)) return null
for (const statement of page.statements) for (const support of statement.supports) {
const parent = this.read(support.memoryId, access)
if (!parent || parent.state !== 'active' || parent.revision !== support.revision || !this.current(parent)) return null
}
return page
}
forget(id: string, expectedRevision: number, access: MemoryAccess): { deletedIds: string[]; deletedTopicIds: string[]; alreadyDeliveredContent: 'not_erased' } {
return this.transaction(() => {
this.requireRecord(id, expectedRevision, access, true)
const affected = this.forgetDependencies(id)
const sourceIds = new Set<string>()
const topicIds = new Set<string>()
for (const record of affected) {
for (const row of this.db.prepare(`SELECT source_id FROM evidence WHERE memory_id = ?
UNION SELECT source_id FROM source_dependencies WHERE memory_id = ?
UNION SELECT source_id FROM memory_support WHERE memory_id = ?`).all(record.id, record.id, record.id)) sourceIds.add(String(row.source_id))
for (const row of this.db.prepare('SELECT topic_id FROM topic_dependencies WHERE memory_id = ?').all(record.id)) topicIds.add(String(row.topic_id))
}
for (const sourceId of sourceIds) {
const source = this.rawSource(sourceId)
for (const root of [sourceId, ...(source?.rootIds ?? [])]) this.db.prepare('INSERT OR IGNORE INTO suppressed_sources(key, at) VALUES(?, ?)').run(this.suppressionKey(root), this.now())
}
this.learning.invalidateSources(sourceIds)
for (const record of affected) {
this.invalidateTopics(record.id)
this.notebook.changed(record)
this.db.prepare('DELETE FROM memory_fts WHERE rowid = (SELECT rowid FROM memories WHERE id = ?)').run(record.id)
this.db.prepare('DELETE FROM memories WHERE id = ?').run(record.id)
this.db.prepare('INSERT INTO tombstones(id, last_revision, at) VALUES(?, ?, ?)').run(record.id, record.revision, this.now())
}
this.notebook.pruneEmpty()
this.bumpKnowledgeEpoch()
for (const sourceId of sourceIds) {
const quotes = this.db.prepare('SELECT quote FROM evidence WHERE source_id = ? UNION SELECT quote FROM memory_support WHERE source_id = ?')
.all(sourceId, sourceId).map(row => String(row.quote))
if (!quotes.length) this.db.prepare('DELETE FROM sources WHERE id = ?').run(sourceId)
else {
// Shared events retain only the evidence spans still owned by remaining records.
const source = this.rawSource(sourceId)!
source.text = retainExcerpts(source.text, quotes)
source.retention = 'evidence_only'
this.db.prepare('UPDATE sources SET data = ? WHERE id = ?').run(JSON.stringify(source), sourceId)
}
}
return { deletedIds: affected.map(record => record.id), deletedTopicIds: [...topicIds], alreadyDeliveredContent: 'not_erased' as const }
})
}
private included(projectId: string | null | undefined): boolean {
return projectId == null || this.db.prepare('SELECT included FROM projects WHERE id = ?').get(projectId)?.included === 1
}
private sourceIncluded(source: SourceEvent): boolean {
if (!this.included(source.projectId) || !this.sessionPolicy(source.engine, source.sessionId).included) return false
return source.rootIds.every(id => {
if (id === source.id) return true
const root = this.rawSource(id)
return !!root && this.included(root.projectId) && this.sessionPolicy(root.engine, root.sessionId).included
})
}
private evidenceIncluded(record: MemoryRecord): boolean {
return record.evidence.every(evidence => {
const source = this.rawSource(evidence.sourceEventId)
return !!source && this.sourceIncluded(source)
})
}
private cancelHiddenSources(): void {
this.learning.invalidateSources(this.db.prepare('SELECT DISTINCT s.data FROM memory_job_sources j JOIN sources s ON s.id=j.source_id').all()
.map(row => JSON.parse(String(row.data)) as SourceEvent).filter(source => !this.sourceIncluded(source)).map(source => source.id))
}
private reconcileVisibleConflicts(): void {
const candidates = this.db.prepare(`SELECT m.id FROM memories m WHERE m.state='active' AND EXISTS
(SELECT 1 FROM memories peer WHERE peer.scope_key=m.scope_key AND peer.conflict_key=m.conflict_key
AND peer.id!=m.id AND peer.state IN ('active','needs_verification'))`).all()
for (const { id } of candidates) {
const record = this.record(this.db.prepare('SELECT data FROM memories WHERE id=?').get(id)!)
if (record.state !== 'active' || !this.evidenceIncluded(record)) continue
this.withholdConflicts(record)
if (record.state !== 'active') this.writeRecord({ ...record, revision: record.revision + 1, updatedAt: this.now() })
}
}
private locatorKey(locator: ProjectLocator): string {
if (!['git_common_directory', 'directory'].includes(locator.kind) || !isAbsolute(locator.path)
|| locator.path.length > 4096 || /[\x00-\x1f\x7f]/.test(locator.path)) throw new MemoryError('invalid_locator')
return digest([locator.kind, locator.path])
}
private current(record: MemoryRecord, now = this.now()): boolean {
return (record.validity.validFrom === null || record.validity.validFrom <= now)
&& (record.validity.validUntil === null || record.validity.validUntil > now)
}
private allowed(scope: MemoryScope, access: MemoryAccess): boolean {
return scope.profileId === this.profileId && canAccess(scope, access) && this.included(scope.projectId)
}
private rawSource(id: string): SourceEvent | null {
const row = this.db.prepare('SELECT data FROM sources WHERE id = ?').get(id)
return row ? JSON.parse(String(row.data)) as SourceEvent : null
}
private suppressionKey(root: string): string { return digest([this.profileId, root]) }
private isSuppressed(source: Pick<SourceEvent, 'id' | 'rootIds'>): boolean {
return [source.id, ...source.rootIds].some(root => !!this.db.prepare('SELECT key FROM suppressed_sources WHERE key = ?').get(this.suppressionKey(root)))
}
private validateEvidence(draft: MemoryDraft): MemoryState {
const sources = new Map<string, SourceEvent>()
for (const evidence of draft.evidence) {
if (this.isSuppressed({ id: evidence.sourceEventId, rootIds: [] })) throw new MemoryError('source_suppressed')
const source = this.rawSource(evidence.sourceEventId)
if (!source) throw new MemoryError('evidence_missing')
if (this.isSuppressed(source)) throw new MemoryError('source_suppressed')
if (!this.sourceIncluded(source)) throw new MemoryError('source_ineligible')
for (const dependency of source.derivedFrom ?? []) {
const row = this.db.prepare('SELECT data FROM memories WHERE id = ?').get(dependency.memoryId)
const parent = row ? this.record(row) : null
if (!parent || parent.revision !== dependency.revision || parent.state !== 'active' || !this.current(parent)) throw new MemoryError('stale_dependency')
}
sources.set(source.id, source)
}
return admission(draft, sources)
}
private assertWritable(scope: MemoryScope, access: MemoryAccess, generation: number, userAction = false): void {
if (!this.allowed(scope, access)) throw new MemoryError('scope_denied')
const controls = this.controls()
if (!userAction && !controls.learn) throw new MemoryError('learning_off')
if (controls.generation !== generation) throw new MemoryError('generation_changed')
}
private requireRecord(id: string, revision: number, access: MemoryAccess, allowExcluded = false): MemoryRecord {
const row = this.db.prepare('SELECT data FROM memories WHERE id = ?').get(id)
const record = row ? this.record(row) : null
if (!record || record.scope.profileId !== this.profileId || !canAccess(record.scope, access)
|| (!allowExcluded && (!this.included(record.scope.projectId) || !this.evidenceIncluded(record)))) throw new MemoryError('not_found')
if (record.revision !== revision) throw new MemoryError('revision_conflict')
return record
}
private withholdConflicts(record: MemoryRecord): MemoryRecord[] {
if (record.state !== 'active') return []
const peers = this.db.prepare("SELECT data FROM memories WHERE scope_key = ? AND conflict_key = ? AND id != ? AND state IN ('active', 'needs_verification')")
.all(canonical(record.scope), record.conflictKey, record.id).map(row => this.record(row))
.filter(peer => this.evidenceIncluded(peer) && peer.claim !== record.claim && conditionsOverlap(peer.applicability, record.applicability))
if (!peers.length) return []
record.state = 'needs_verification'
for (const peer of peers) {
if (peer.state === 'needs_verification') continue
peer.revision++
peer.state = 'needs_verification'
peer.updatedAt = this.now()
this.writeRecord(peer)
}
return peers
}
private writeRecord(record: MemoryRecord, invalidateDescendants = true): void {
const old = this.db.prepare('SELECT data FROM memories WHERE id=?').get(record.id)
const previous = old ? this.record(old) : null
this.bumpKnowledgeEpoch()
this.invalidateTopics(record.id)
this.db.prepare(`INSERT INTO memories(id, revision, project_id, task_id, branch_id, scope_key, conflict_key, state, fingerprint, data)
VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(id) DO UPDATE SET revision=excluded.revision,
project_id=excluded.project_id, task_id=excluded.task_id, branch_id=excluded.branch_id, scope_key=excluded.scope_key,
conflict_key=excluded.conflict_key, state=excluded.state, fingerprint=excluded.fingerprint, data=excluded.data`)
.run(record.id, record.revision, record.scope.projectId ?? null, record.scope.taskId ?? null, record.scope.branchId ?? null,
canonical(record.scope), record.conflictKey, record.state, proposalFingerprint(asDraft(record)), JSON.stringify(record))
this.db.prepare('INSERT INTO revisions(memory_id, revision, data) VALUES(?, ?, ?)').run(record.id, record.revision, JSON.stringify(record))
for (const evidence of record.evidence) this.db.prepare('INSERT OR IGNORE INTO evidence(memory_id, revision, source_id, quote) VALUES(?, ?, ?, ?)')
.run(record.id, record.revision, evidence.sourceEventId, evidence.quote)
const rowid = this.db.prepare('SELECT rowid FROM memories WHERE id = ?').get(record.id)!.rowid
this.db.prepare('DELETE FROM memory_fts WHERE rowid = ?').run(rowid)
if (record.state === 'active') this.db.prepare('INSERT INTO memory_fts(rowid, claim, rationale, cues) VALUES(?, ?, ?, ?)')
.run(rowid, record.claim, record.rationale, record.retrievalCues.join(' '))
if (previous && (canonical(previous.scope) !== canonical(record.scope) || previous.facet !== record.facet)) this.notebook.changed(previous)
this.notebook.changed(record)
if (invalidateDescendants) {
// Follow only the evidence of each current record, not obsolete historical dependencies.
// UNION terminates even when successive revisions form a cycle between record identities.
const descendants = this.db.prepare(`WITH RECURSIVE affected(id) AS (
SELECT e.memory_id FROM source_dependencies d JOIN evidence e ON e.source_id = d.source_id
JOIN memories m ON m.id = e.memory_id AND m.revision = e.revision
WHERE d.memory_id = ? AND d.revision != ?
UNION SELECT e.memory_id FROM affected a JOIN source_dependencies d ON d.memory_id = a.id
JOIN evidence e ON e.source_id = d.source_id JOIN memories m ON m.id = e.memory_id AND m.revision = e.revision
) SELECT m.data FROM affected a JOIN memories m ON m.id = a.id WHERE m.id != ?`).all(record.id, record.revision, record.id)
for (const row of descendants) {
const dependent = this.record(row)
if (!['active', 'tentative'].includes(dependent.state)) continue
this.writeRecord({ ...dependent, revision: dependent.revision + 1, state: 'needs_verification', updatedAt: this.now() }, false)
}
}
}
private recordSupport(record: MemoryRecord, draft: MemoryDraft): void {
if (['inferred', 'imported'].includes(draft.evidenceClass)) return
let changed = false
for (const evidence of draft.evidence) {
if (!evidence.paths.includes('/claim')) continue
const source = this.rawSource(evidence.sourceEventId)!
const kind = source.role === 'user' ? 'user_statement'
: source.role === 'tool' && evidence.verification ? 'verified_observation' : null
// Derived summaries and assistant repetitions never create independent confirmation.
if (!kind || source.derivedFrom) continue
for (const root of source.rootIds) {
const result = this.db.prepare(`INSERT OR IGNORE INTO memory_support
(memory_id, fingerprint, root_id, source_id, quote, kind, session_key, observed_at) VALUES(?, ?, ?, ?, ?, ?, ?, ?)`)
.run(record.id, proposalFingerprint(draft), root, source.id, evidence.quote, kind,
digest([source.engine, source.sessionId]), source.observedAt) as { changes: number | bigint }
if (Number(result.changes) > 0) changed = true
}
}
// Independent support can connect overlapping evidence and expand a future forget operation,
// without revising the meaning. Replayed roots do not change that dependency snapshot.
if (changed) this.bumpKnowledgeEpoch()
}
private invalidateLearning(previous: MemoryRecord): void {
this.learning.invalidateSources([...previous.evidence.map(evidence => evidence.sourceEventId),
...this.db.prepare('SELECT source_id FROM memory_support WHERE memory_id=? AND fingerprint=?')
.all(previous.id, proposalFingerprint(asDraft(previous))).map(row => String(row.source_id)),
])
}
private forgetDependencies(id: string): MemoryRecord[] {
const pending = [id]
const affected = new Map<string, MemoryRecord>()
while (pending.length) {
const current = pending.pop()!
if (affected.has(current)) continue
const row = this.db.prepare('SELECT data FROM memories WHERE id = ?').get(current)
if (!row) continue
affected.set(current, this.record(row))
for (const dependent of this.db.prepare(`SELECT DISTINCT e.memory_id FROM source_dependencies d
JOIN evidence e ON e.source_id = d.source_id WHERE d.memory_id = ?`).all(current)) pending.push(String(dependent.memory_id))
for (const owned of this.db.prepare(`SELECT source_id, quote FROM evidence WHERE memory_id = ?
UNION SELECT source_id, quote FROM memory_support WHERE memory_id = ?`).all(current, current)) {
const source = this.rawSource(String(owned.source_id))
if (!source) continue
for (const shared of this.db.prepare(`SELECT memory_id, quote FROM evidence WHERE source_id = ?
UNION SELECT memory_id, quote FROM memory_support WHERE source_id = ?`).all(owned.source_id, owned.source_id)) {
// A broad quote can contain forgotten knowledge even when its record has a different claim.
// Conservatively forget that dependent record rather than preserve the deleted excerpt.
if (quotesOverlap(source.text, String(owned.quote), String(shared.quote))) pending.push(String(shared.memory_id))
}
}
}
return [...affected.values()]
}
private invalidateTopics(memoryId: string): void {
this.db.prepare('UPDATE topics SET data = NULL WHERE id IN (SELECT topic_id FROM topic_dependencies WHERE memory_id = ?)').run(memoryId)
}
/** Separate from capture consent: a batch may publish several records under one learning lease. */
private bumpKnowledgeEpoch(): void {
this.db.exec("UPDATE memory_meta SET value=CAST(value AS INTEGER)+1 WHERE key='knowledge_epoch'")
}
private scopeFilter(access: MemoryAccess, alias = 'm'): { sql: string; params: unknown[] } {
if (access.projectIds.length > 1_000) throw new MemoryError('scope_too_broad')
const clauses: string[] = []
const params: unknown[] = []
if (access.includeProfile) clauses.push(`${alias}.project_id IS NULL`)
if (access.projectIds.length) {
clauses.push(`(${alias}.project_id IN (${access.projectIds.map(() => '?').join(',')}) AND ${alias}.project_id IN (SELECT id FROM projects WHERE included = 1))`)
params.push(...access.projectIds)
}
return { sql: `(${clauses.join(' OR ') || '0'}) AND (${alias}.task_id IS NULL OR ${alias}.task_id = ?) AND (${alias}.branch_id IS NULL OR ${alias}.branch_id = ?)`, params: [...params, access.taskId ?? null, access.branchId ?? null] }
}
private record(row: Record<string, unknown>): MemoryRecord { return JSON.parse(String(row.data)) as MemoryRecord }
private transaction<T>(operation: () => T): T {
const level = this.transactionDepth
this.db.exec(level ? `SAVEPOINT memory_${level}` : 'BEGIN IMMEDIATE')
this.transactionDepth++
try {
const result = operation()
this.db.exec(level ? `RELEASE memory_${level}` : 'COMMIT')
return result
} catch (error) {
try { this.db.exec(level ? `ROLLBACK TO memory_${level}; RELEASE memory_${level}` : 'ROLLBACK') } catch { /* Original failure is more useful. */ }
throw error
} finally {
this.transactionDepth--
}
}
}
function retainExcerpts(text: string, quotes: string[]): string {
const spans = quotes.map(quote => {
const start = text.indexOf(quote)
if (start < 0) throw new MemoryError('evidence_mismatch')
return { start, end: start + quote.length }
}).sort((a, b) => a.start - b.start)
const merged: Array<{ start: number; end: number }> = []
for (const span of spans) {
const previous = merged.at(-1)
if (previous && span.start <= previous.end) previous.end = Math.max(previous.end, span.end)
else merged.push({ ...span })
}
// A one-character separator never expands the original source size. Each exact evidence span
// survives; the retention marker makes clear that surrounding conversation text was removed.
return merged.map(span => text.slice(span.start, span.end)).join('\n')
}
/** Same scalar/array overlap semantics as matches(), applied before the candidate limit. */
function applicabilitySql(required: string): string {
return `NOT EXISTS (SELECT 1 FROM json_each(${required}) requirement WHERE NOT EXISTS (
SELECT 1 FROM json_each((SELECT actual FROM context)) actual WHERE actual.key = requirement.key AND CASE
WHEN requirement.type = 'array' AND actual.type = 'array' THEN EXISTS (
SELECT 1 FROM json_each(requirement.value) r, json_each(actual.value) a WHERE r.type = a.type AND r.value = a.value)
WHEN requirement.type = 'array' THEN EXISTS (
SELECT 1 FROM json_each(requirement.value) r WHERE r.type = actual.type AND r.value = actual.value)
WHEN actual.type = 'array' THEN EXISTS (
SELECT 1 FROM json_each(actual.value) a WHERE a.type = requirement.type AND a.value = requirement.value)
ELSE requirement.type = actual.type AND requirement.value = actual.value END))`
}
function asDraft(record: MemoryRecord): MemoryDraft {
const { schemaVersion: _schema, id: _id, revision: _revision, state: _state, createdAt: _created, updatedAt: _updated, ...draft } = record
return draft
}
function bounded(value: number | undefined, fallback: number, min: number, max: number): number {
return typeof value === 'number' && Number.isFinite(value) ? Math.min(max, Math.max(min, Math.trunc(value))) : fallback
}
function quotesOverlap(text: string, first: string, second: string): boolean {
for (let a = text.indexOf(first); a !== -1; a = text.indexOf(first, a + 1)) {
// An overlapping occurrence starts no earlier than this and ends after a.
const b = text.indexOf(second, Math.max(0, a - second.length + 1))
if (b !== -1 && b < a + first.length) return true
}
return false
}