Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -241,6 +241,8 @@ Concurrent deletion locking is outside this contract.
`MEMORY_WRITE_LOCK` (`src/state/memory-utils.ts`) serializes Memory saves, deletes,
relations, evolution, and auto-forget demotion. Before demoting, auto-forget rechecks both
live rows under the lock and reports only completed demotions; dry runs report snapshot matches.
Mesh receive, mesh sync and heal hold the same lock across each Memory write and its index update.
Heal rechecks the stored supersession edge under the lock before demoting.
Consolidation checks the predecessor again under the lock after the provider call. Release the
lock before graph eviction. Import and snapshot restore keep their own replacement semantics.
Eviction decrements image references after deleting the row and logs a failed release without
Expand Down Expand Up @@ -425,8 +427,9 @@ Memories, not Lessons.
and it is not yet injected; it goes directly above the first passed Memory it shadows, within
the 3 results, and skips the gate.
- **De-indexing** — every path that sets a Memory `isLatest: false` (`mem::remember`, `mem::evolve`,
`mem::consolidate`, `mem::auto-forget`) calls `deindexSupersededMemory()`; evolve and
consolidate index the new version with `indexNewMemoryVersion()` (`src/functions/search.ts`).
`mem::consolidate`, `mem::auto-forget`, `mem::heal`, mesh receive and sync) calls
`deindexSupersededMemory()`; every other path that writes a latest Memory (evolve, consolidate,
`mem::auto-page`, mesh) indexes it with `indexNewMemoryVersion()` (`src/functions/search.ts`).
- **Keyed Semantic Facts** — see the `SemanticMemory` consistency rule; a keyed fact whose text
matches an unkeyed one keys it when every Session that fact cites is this project's, so the
corpus written before keys can be superseded without one project closing another's fact.
Expand Down
5 changes: 4 additions & 1 deletion docs/supersession.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,10 @@ when the newest claim was already given, an older one is not admitted in its pla
removes the row from BM25 and the vector index. `mem::evolve` and the evolve branch of
`mem::consolidate` add the new version through `indexNewMemoryVersion()`, so a replaced Memory is
neither returned nor the only hit (T5, T6). A Memory `mem::consolidate` creates fresh (no
predecessor) is still not added to the live index until the next boot. A daemon restart rebuilds
predecessor), one `mem::auto-page` archives and a latest one mesh receive or sync accepts enter the
live index the same way; `mem::heal` and a non-latest mesh row leave it through
`deindexSupersededMemory()` (`test/memory-write-indexing.test.ts`, unscoped smart-search).
Fresh consolidation and auto-page do not supersede a Memory. A daemon restart rebuilds
BM25 from content and skips non-latest Memories. `mem::evict` deletes a non-latest Memory after
`nonLatestMemoryMaxDays`; `AGENTMEMORY_NONLATEST_FILTER` stays off by default.

Expand Down
1 change: 1 addition & 0 deletions src/functions/consolidate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -237,6 +237,7 @@ export function registerConsolidateFunction(
...(scopedProject !== undefined && { project: scopedProject }),
};
await kv.set(KV.memories, memory.id, memory);
await indexNewMemoryVersion(memory);
existingMemories.push(memory);
writtenTitles.add(memory.title.toLowerCase());
await recordAudit(kv, "remember", "mem::consolidate", [memory.id], {
Expand Down
38 changes: 21 additions & 17 deletions src/functions/diagnostics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@ import type { ISdk } from "../engine/types.js";
import type { StateKV } from "../state/kv.js";
import { KV } from "../state/schema.js";
import { withKeyedLock } from "../state/keyed-mutex.js";
import { MEMORY_WRITE_LOCK } from "../state/memory-utils.js";
import { deindexSupersededMemory } from "./search.js";
import { recordAudit } from "./audit.js";
import { storeAcceptsWrite } from "../health/store-probe.js";
import { readMissedInjections } from "../hooks/_missed-injection.js";
Expand Down Expand Up @@ -768,30 +770,32 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void {
}

for (const memory of memories) {
if (memory.isLatest && supersededBy.has(memory.id)) {
const successorId = supersededBy.get(memory.id);
if (memory.isLatest && successorId && successorId !== memory.id) {
if (dryRun) {
details.push(
`[dry-run] Would set isLatest=false on memory "${memory.title}" (${memory.id})`,
);
fixed++;
continue;
}
const didFix = await withKeyedLock(
`mem:memory:${memory.id}`,
async () => {
const fresh = await kv.get<Memory>(KV.memories, memory.id);
if (!fresh || !fresh.isLatest) return false;
fresh.isLatest = false;
fresh.updatedAt = new Date().toISOString();
await kv.set(KV.memories, fresh.id, fresh);
await recordAudit(kv, "heal", "mem::heal", [fresh.id], {
entityType: "memory",
reason: "superseded-memory-mark-non-latest",
action: "update",
});
return true;
},
);
const didFix = await withKeyedLock(MEMORY_WRITE_LOCK, async () => {
const [fresh, successor] = await Promise.all([
kv.get<Memory>(KV.memories, memory.id),
kv.get<Memory>(KV.memories, successorId),
]);
if (!fresh?.isLatest || !successor?.supersedes?.includes(fresh.id)) return false;
await kv.set(KV.memories, fresh.id, {
...fresh, isLatest: false, updatedAt: new Date().toISOString(),
});
deindexSupersededMemory(fresh.id);
await recordAudit(kv, "heal", "mem::heal", [fresh.id], {
entityType: "memory",
reason: "superseded-memory-mark-non-latest",
action: "update",
});
return true;
});
if (didFix) {
details.push(
`Set isLatest=false on memory "${memory.title}" (${memory.id})`,
Expand Down
47 changes: 23 additions & 24 deletions src/functions/mesh.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,13 @@ import type { ISdk } from "../engine/types.js";
import type { StateKV } from "../state/kv.js";
import { KV, generateId } from "../state/schema.js";
import { withKeyedLock } from "../state/keyed-mutex.js";
import { MEMORY_WRITE_LOCK } from "../state/memory-utils.js";
import {
indexGraphEdge,
indexGraphNode,
graphLegDisabled,
} from "../state/graph-indexes.js";
import { deindexSupersededMemory, indexNewMemoryVersion } from "./search.js";
import { recordAudit } from "./audit.js";
import { capRecordProvenance } from "./graph-provenance.js";
import { GRAPH_WRITE_LOCK } from "./graph.js";
Expand Down Expand Up @@ -82,7 +84,7 @@ async function lwwMergeList<T extends { id: string }>(
kv: StateKV,
scope: string,
items: T[] | undefined,
lockPrefix: string,
lockKey: (id: string) => string,
tsField: "updatedAt" | "createdAt",
onWrite?: (item: T) => Promise<void>,
): Promise<number> {
Expand All @@ -92,27 +94,24 @@ async function lwwMergeList<T extends { id: string }>(
if (!item.id || typeof item.id !== "string") continue;
const ts = (item as Record<string, unknown>)[tsField];
if (typeof ts !== "string" || Number.isNaN(new Date(ts).getTime())) continue;
const wrote = await withKeyedLock(`${lockPrefix}:${item.id}`, async () => {
const wrote = await withKeyedLock(lockKey(item.id), async () => {
const existing = await kv.get<T>(scope, item.id);
if (!existing) {
await kv.set(scope, item.id, item);
return true;
}
const existingTs = (existing as Record<string, unknown>)[tsField] as string;
if (new Date(ts) > new Date(existingTs)) {
await kv.set(scope, item.id, item);
return true;
}
return false;
});
if (wrote) {
count++;
const existingTs = existing && (existing as Record<string, unknown>)[tsField] as string | undefined;
if (existing && !(new Date(ts) > new Date(existingTs!))) return false;
await kv.set(scope, item.id, item);
if (onWrite) await onWrite(item);
}
return true;
});
if (wrote) count++;
}
return count;
}

async function reindexMergedMemory(memory: Memory): Promise<void> {
deindexSupersededMemory(memory.id);
if (memory.isLatest) await indexNewMemoryVersion(memory);
}

function graphNodeTs(node: GraphNode): string {
return node.updatedAt || node.createdAt;
}
Expand Down Expand Up @@ -354,9 +353,9 @@ export function registerMeshFunction(
}
let accepted = 0;

accepted += await lwwMergeList(kv, KV.memories, data.memories, "mem:memory", "updatedAt");
accepted += await lwwMergeList(kv, KV.semantic, data.semantic, "mem:semantic", "updatedAt");
accepted += await lwwMergeList(kv, KV.procedural, data.procedural, "mem:procedural", "updatedAt");
accepted += await lwwMergeList(kv, KV.memories, data.memories, () => MEMORY_WRITE_LOCK, "updatedAt", reindexMergedMemory);
accepted += await lwwMergeList(kv, KV.semantic, data.semantic, (id) => `mem:semantic:${id}`, "updatedAt");
accepted += await lwwMergeList(kv, KV.procedural, data.procedural, (id) => `mem:procedural:${id}`, "updatedAt");
if (data.relations && Array.isArray(data.relations)) {
for (const rel of data.relations) {
if (!rel.sourceId || !rel.targetId || !rel.type) continue;
Expand All @@ -380,7 +379,7 @@ export function registerMeshFunction(
kv,
KV.graphEdges,
data.graphEdges?.map(capRecordProvenance),
"mem:gedge",
(id) => `mem:gedge:${id}`,
"createdAt",
(edge) => indexGraphEdge(kv, edge),
)),
Expand Down Expand Up @@ -519,13 +518,13 @@ async function applySyncData(
let applied = 0;

if (scopes.includes("memories")) {
applied += await lwwMergeList(kv, KV.memories, data.memories, "mem:memory", "updatedAt");
applied += await lwwMergeList(kv, KV.memories, data.memories, () => MEMORY_WRITE_LOCK, "updatedAt", reindexMergedMemory);
}
if (scopes.includes("semantic")) {
applied += await lwwMergeList(kv, KV.semantic, data.semantic, "mem:semantic", "updatedAt");
applied += await lwwMergeList(kv, KV.semantic, data.semantic, (id) => `mem:semantic:${id}`, "updatedAt");
}
if (scopes.includes("procedural")) {
applied += await lwwMergeList(kv, KV.procedural, data.procedural, "mem:procedural", "updatedAt");
applied += await lwwMergeList(kv, KV.procedural, data.procedural, (id) => `mem:procedural:${id}`, "updatedAt");
}
if (scopes.includes("relations") && data.relations) {
for (const rel of data.relations) {
Expand Down Expand Up @@ -554,7 +553,7 @@ async function applySyncData(
kv,
KV.graphEdges,
data.graphEdges?.map(capRecordProvenance),
"mem:gedge",
(id) => `mem:gedge:${id}`,
"createdAt",
(edge) => indexGraphEdge(kv, edge),
),
Expand Down
2 changes: 2 additions & 0 deletions src/functions/working-memory.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import type { ISdk } from "../engine/types.js";
import type { Memory } from "../types.js";
import { KV, generateId } from "../state/schema.js";
import { StateKV } from "../state/kv.js";
import { indexNewMemoryVersion } from "./search.js";
import { recordAudit } from "./audit.js";
import { recordAccessBatch } from "./access-tracker.js";
import { logger } from "../logger.js";
Expand Down Expand Up @@ -231,6 +232,7 @@ export function registerWorkingMemoryFunctions(
isLatest: true,
};
await kv.set(KV.memories, archivalMemory.id, archivalMemory);
await indexNewMemoryVersion(archivalMemory);
await kv.delete(CORE_SCOPE, entry.id);

totalTokens -= tokens;
Expand Down
Loading