@oortmem/core 0.3.0 → 0.4.0

package/dist/recall.d.ts

@@ -1,10 +1,25 @@
 import type { Embedder, MemoryStore, Reranker, ScopeFilter } from './adapters.js';
 import type { ResolvedConfig } from './config.js';
+import { type Grant, type Home } from './grant.js';
+import { type IncludeLevel, type MemoryOrigin } from './levels.js';
 import { type Memory } from './model.js';
 import { type RecallMode } from './temporal.js';
 export interface RecallQuery {
     text: string;
-    scope: ScopeFilter;
+    /**
+     * Who recalls, as a pre-level filter: read with `localGrant(scope, { home })`, the person's
+     * Planet plus this agent's own Star in these projects. Required unless `grant` is given.
+     */
+    scope?: ScopeFilter;
+    /** The grant to read with, instead of one built from `scope` (multi-node grants, tests). */
+    grant?: Grant;
+    /** With `scope`: where this agent's memories land (`star` for an agent configured as a Star). */
+    home?: Home;
+    /**
+     * Which levels to read (spec 7.1), intersected with the grant. A level the grant does not cover
+     * rejects with `ScopeDeniedError`. Default: every node the grant reads.
+     */
+    include?: IncludeLevel[];
     budgetChars?: number;
     /** ISO timestamp: recall what was true then (valid time). Implies `mode: 'as-of'`. */
     asOf?: string;
@@ -44,6 +59,8 @@ export interface RecalledMemory extends Memory {
         /** A volatile fact nobody confirmed within `recall.staleAfterDays`. */
         stale?: true;
     };
+    /** Where it came from: level, node, author, and whether a narrower memory overrides it. */
+    origin?: MemoryOrigin;
 }
 export type Degradation = 'no-embedder' | 'no-reranker' | 'embed-failed' | 'rerank-failed'
 /** The reranker returned no ids: the fused order stands. */
@@ -75,6 +92,8 @@ export interface RecallResult {
     embedSkipped?: 'lexical-confident';
     /** The temporal view this recall read. Always set by `recall`. */
     temporal?: RecallTemporal;
+    /** The nodes this recall read, as labels show them (`your Planet`, `Star cursor`). */
+    read?: string[];
     timings: Record<string, number>;
 }
 export interface RecallDeps {
@@ -107,3 +126,10 @@ export declare function fitForInjection<M extends RecalledMemory>(memories: M[],
     kept: M[];
     lines: string[];
 };
+/**
+ * Memory text with any `<oort-…` or `</oort-…` tag opening written as `&lt;`, so a memory cannot
+ * close the `<oort-memory>` block (or open another) and have what follows read as the prompt.
+ */
+export declare function escapeBlockTags(text: string): string;
+/** The share of an injection budget hive memories may take (spec 7.2). */
+export declare const HIVE_QUOTA = 0.4;

package/dist/recall.js

@@ -1,6 +1,8 @@
 import { activation } from './activation.js';
 import { fuse, isVisible } from './fusion.js';
-import { localGrant } from './grant.js';
+import { addressOf, nodeKey, nodeOf } from './address.js';
+import { assertGrant, grantWrites, localGrant, narrowGrant, } from './grant.js';
+import { contradicted, escapeLabelText, nodeLabel, nodesToRead, originOf, specificity, specificityFactor, } from './levels.js';
 import { scrub } from './scrub.js';
 import { isCurrent } from './model.js';
 import { temporalIntent } from './temporal.js';
@@ -17,8 +19,14 @@ const clock = () => performance.now();
  */
 export async function recall(q, deps) {
     const { store, config } = deps;
-    // The store enforces scope; recall reads and hydrates only inside q.scope.
-    const grant = localGrant(q.scope);
+    const full = grantOf(q);
+    // The nodes to read: the grant intersected with `include` (a level it lacks rejects here,
+    // before anything is read). Recall reads and hydrates only inside them; the store enforces it.
+    const nodes = nodesToRead(full, q.include);
+    const grant = narrowGrant(full, nodes);
+    // First stage per node (spec 7.2), then nodes merged by fused score. One node: today's recall.
+    const legs = nodes.map((n) => ({ node: n, grant: narrowGrant(full, [n]) }));
+    const epsilon = config.recall.specificityPrior;
     const now = deps.now ?? new Date();
     // Scrub once: the query text reaches embedders and rerankers, which may be remote. Temporal
     // words ("on 2 April", "changed over time") pick the view and are not searched for.
@@ -54,14 +62,14 @@ export async function recall(q, deps) {
         prefetched.set(id, m);
         return m;
     };
-    const lexicalP = timed('lexicalMs', () => store.lexical(grant, text, config.recall.lexicalK));
+    const lexicalP = timed('lexicalMs', () => Promise.all(legs.map((l) => store.lexical(l.grant, text, config.recall.lexicalK))));
     // A failed embed must not leave the lexical promise unobserved.
     lexicalP.catch(() => { });
     // Lexical first (CON-57): when the lexical answer is already clear, skip the embedding round
     // trip. Otherwise the lexical search has run while nothing else waited on it.
     let embedSkipped;
     if (deps.embed && config.recall.lexicalFirst) {
-        const first = await lexicalP;
+        const first = byRank(await lexicalP);
         if (await lexicalIsConfident(first, queryTokens, read, now, view)) {
             embedSkipped = 'lexical-confident';
         }
@@ -83,15 +91,24 @@ export async function recall(q, deps) {
         timings['embedMs'] = clock() - t;
     }
     const v = vector;
-    const [lexical, dense] = await Promise.all([
+    let denseFailed = false;
+    const [lexicalLegs, denseLegs] = await Promise.all([
         lexicalP,
         v === undefined
-            ? Promise.resolve([])
-            : timed('denseMs', () => store.dense(grant, v, config.recall.denseK).catch(() => {
-                degraded.push('dense-failed');
+            ? Promise.resolve(legs.map(() => []))
+            : timed('denseMs', () => Promise.all(legs.map((l) => store.dense(l.grant, v, config.recall.denseK).catch(() => {
+                denseFailed = true;
                 return [];
-            })),
+            })))),
     ]);
+    if (denseFailed)
+        degraded.push('dense-failed');
+    // Across nodes, by rank (one node: its own list). Used where one list is needed.
+    const lexical = byRank(lexicalLegs);
+    const dense = byRank(denseLegs);
+    // Ranks are per node: each node's first stage ranks its own memories.
+    const lexicalRank = rankWithin(lexicalLegs);
+    const denseRank = rankWithin(denseLegs);
     // Live rows only: a cold row keeps its text, stub and entities, which is all fusion, the gate
     // and the reranker read. Hydration waits until we know what is returned (CON-47).
     const ids = [...new Set([...lexical, ...dense].map((h) => h.id))];
@@ -101,7 +118,14 @@ export async function recall(q, deps) {
         if (m !== null)
             memories.set(m.id, m);
     const tf = clock();
-    const fused = fuse([lexical, dense], memories, now, { activation: config.activation, view });
+    // Reciprocal rank fusion within each node as before, then the nodes merged by fused score,
+    // each scaled by the specificity prior (off at ε = 0). A stable sort: one node keeps its order.
+    const fused = legs
+        .flatMap((l, i) => fuse([lexicalLegs[i], denseLegs[i]], memories, now, {
+        activation: config.activation,
+        view,
+    }).map((f) => epsilon === 0 ? f : { ...f, score: f.score * specificityFactor(l.node, epsilon) }))
+        .sort((x, y) => y.score - x.score);
     timings['fuseMs'] = clock() - tf;
     const coverage = new Map();
     for (const f of fused) {
@@ -168,13 +192,13 @@ export async function recall(q, deps) {
     };
     const kept = candidates.filter((f) => relevant(f.id));
     const dropped = candidates.length - kept.length;
-    const out = [];
+    let out = [];
     for (const f of kept) {
         const m = memories.get(f.id);
         if (m === undefined)
             continue;
-        const lr = lexical.findIndex((h) => h.id === f.id);
-        const dr = dense.findIndex((h) => h.id === f.id);
+        const lr = lexicalRank.get(f.id) ?? -1;
+        const dr = denseRank.get(f.id) ?? -1;
         const rs = rerankScores.get(f.id);
         const ds = denseScore.get(f.id);
         out.push({
@@ -190,9 +214,13 @@ export async function recall(q, deps) {
                 activation: activation(m.accessLog, m.salience, now, config.activation),
                 hydrated: false,
             },
+            origin: originOf(m, full),
         });
     }
-    let result = view.mode === 'history' ? await withChains(out, read, now, view, queryTokens, config) : out;
+    out = withConflicts(out);
+    let result = view.mode === 'history'
+        ? await withChains(out, full, read, now, view, queryTokens, config)
+        : out;
     for (const m of result) {
         if (isCurrent(m, now) && isStale(m, now, config.recall.staleAfterDays)) {
             m.explanation.stale = true;
@@ -211,6 +239,10 @@ export async function recall(q, deps) {
     result = await Promise.all(result.map(async (m) => {
         if (!touched.has(m.id) || m.tier !== 'cold' || !isCurrent(m, now))
             return m;
+        // Hydrating writes the memory back; a node this caller only reads (the Planet, for a Star
+        // agent) is served from its live row, cold and lexical-only, and left as it is.
+        if (!grantWrites(grant, m))
+            return m;
         try {
             const blob = await store.coldGet(grant, m.id);
             // A lost or torn blob: the memory stays cold, lexical-only.
@@ -264,9 +296,87 @@ export async function recall(q, deps) {
         ...(rerankSkipped !== undefined ? { rerankSkipped } : {}),
         ...(embedSkipped !== undefined ? { embedSkipped } : {}),
         temporal,
+        read: nodes.map((n) => nodeLabel(n, full)),
         timings,
     };
 }
+/** The grant a query reads with: its own, or the local grant for its scope and home. */
+function grantOf(q) {
+    if (q.grant !== undefined) {
+        assertGrant(q.grant);
+        return q.grant;
+    }
+    if (q.scope === undefined)
+        throw new TypeError('recall needs a scope or a grant');
+    return localGrant(q.scope, q.home === undefined ? {} : { home: q.home });
+}
+/**
+ * Per-node hit lists as one list, by rank: every node's first hit, then every node's second, in
+ * node order. With one non-empty node it is exactly that node's list.
+ */
+function byRank(lists) {
+    if (lists.length === 1)
+        return lists[0];
+    const out = [];
+    const seen = new Set();
+    const longest = Math.max(0, ...lists.map((l) => l.length));
+    for (let r = 0; r < longest; r++) {
+        for (const l of lists) {
+            const h = l[r];
+            if (h !== undefined && !seen.has(h.id)) {
+                seen.add(h.id);
+                out.push(h);
+            }
+        }
+    }
+    return out;
+}
+/** Each id's 0-based rank within its own node's list. */
+function rankWithin(lists) {
+    const out = new Map();
+    for (const l of lists) {
+        l.forEach((h, i) => {
+            if (!out.has(h.id))
+                out.set(h.id, i);
+        });
+    }
+    return out;
+}
+const nodeOfMemory = (m) => nodeOf(addressOf(m));
+/**
+ * The conflict rule (spec 7.2), always on: when a returned memory contradicts a returned memory in
+ * another node (recorded by observe as a `level`/`contradicts` decision), the narrower of the two
+ * ranks first and the wider one stays, its origin naming what overrides it. Equally specific: the
+ * memory that recorded the contradiction wins.
+ */
+function withConflicts(out) {
+    const byId = new Map(out.map((m) => [m.id, m]));
+    const list = [...out];
+    for (const m of out) {
+        for (const otherId of contradicted(m)) {
+            const other = byId.get(otherId);
+            if (other === undefined || other === m)
+                continue;
+            const [a, b] = [nodeOfMemory(m), nodeOfMemory(other)];
+            if (nodeKey(a) === nodeKey(b))
+                continue;
+            const [winner, loser] = specificity(b) > specificity(a) ? [other, m] : [m, other];
+            const iw = list.indexOf(winner);
+            const il = list.indexOf(loser);
+            if (iw > il) {
+                list.splice(iw, 1);
+                list.splice(il, 0, winner);
+            }
+            if (loser.origin !== undefined && winner.origin !== undefined) {
+                loser.origin = {
+                    ...loser.origin,
+                    overriddenBy: { id: winner.id, node: winner.origin.node },
+                };
+            }
+        }
+    }
+    return list;
+}
 /** The view a query asks for: explicit options first, else read from the query in code. */
 function viewFor(q, text, now) {
     const at = (iso) => iso ?? now.toISOString();
@@ -305,7 +415,7 @@ const CHAIN_MAX = 8;
  * first-ranked chain first. Corrected versions are skipped (they were never true) but walked
  * through. Versions only the walk found are marked `chain`.
  */
-async function withChains(out, read, now, view, queryTokens, config) {
+async function withChains(out, grantFor, read, now, view, queryTokens, config) {
     const byId = new Map(out.map((m) => [m.id, m]));
     const seen = new Set();
     const result = [];
@@ -341,6 +451,7 @@ async function withChains(out, read, now, view, queryTokens, config) {
                     hydrated: false,
                     chain: true,
                 },
+                origin: originOf(m, grantFor),
             });
         }
     }
@@ -453,20 +564,55 @@ const INJECT_CLOSE = '\n</oort-memory>';
  */
 export function fitForInjection(memories, budgetChars, now = new Date()) {
     let total = INJECT_OPEN.length + INJECT_CLOSE.length;
+    let hive = 0;
     const lines = [];
     const kept = [];
+    // Levels are named only when something comes from outside the reader's home node: a recall of
+    // one node reads exactly as before levels existed.
+    const labelled = memories.some((m) => m.origin !== undefined && !m.origin.home);
     for (const m of memories) {
         const note = m.explanation.stale === true
             ? ` (may be outdated; last confirmed ${age(lastConfirmed(m), now)})`
             : '';
-        const line = `- [${m.type}, ${when(m, now)}] ${scrub(m.text).text}${note}`;
+        const text = scrub(escapeBlockTags(escapeLabelText(m.text))).text;
+        const line = `- [${labelFor(m, labelled, now)}] ${text}${note}`;
         const cost = line.length + (lines.length > 0 ? 1 : 0);
+        // Hive memories (Constellation, Galaxy) take at most HIVE_QUOTA of the budget, so a large team
+        // cannot crowd out the person's own memory: one past it is skipped, not the end of the block.
+        const fromHive = m.origin?.level === 'hive';
+        if (fromHive && hive + cost > HIVE_QUOTA * budgetChars)
+            continue;
         if (total + cost > budgetChars)
             break;
         lines.push(line);
         kept.push(m);
         total += cost;
+        if (fromHive)
+            hive += cost;
     }
     return { kept, lines };
 }
+/**
+ * Memory text with any `<oort-…` or `</oort-…` tag opening written as `&lt;`, so a memory cannot
+ * close the `<oort-memory>` block (or open another) and have what follows read as the prompt.
+ */
+export function escapeBlockTags(text) {
+    return text.replace(/<(?=\s*\/?\s*oort-)/gi, '&lt;');
+}
+/** The share of an injection budget hive memories may take (spec 7.2). */
+export const HIVE_QUOTA = 0.4;
+/**
+ * A memory's label, built by code from structured fields only: `semantic, 2d ago`, or with levels
+ * named `semantic, Star cursor, 5h ago`, and `, overridden by Star cursor` when a narrower memory
+ * in the result contradicts it. Memory text never reaches it (and its brackets are escaped).
+ */
+function labelFor(m, labelled, now) {
+    const parts = [m.type];
+    if (labelled && m.origin !== undefined)
+        parts.push(m.origin.node);
+    parts.push(when(m, now));
+    if (m.origin?.overriddenBy !== undefined)
+        parts.push(`overridden by ${m.origin.overriddenBy.node}`);
+    return parts.join(', ');
+}
 //# sourceMappingURL=recall.js.map

package/dist/store-conformance.js

@@ -388,12 +388,14 @@ export function storeConformance(name, make) {
             const others = {
                 'other-org': { ...localScope(), orgId: 'another-org' },
                 'other-customer': { ...localScope(), customerId: 'someone-else' },
-                'other-agent': { ...localScope(), agentId: 'another-agent' },
             };
             await store.upsert(TG, makeMemory({ id: 'mine', text, embedding }));
             for (const [id, scope] of Object.entries(others)) {
                 await store.upsert(grantFor(scope), makeMemory({ id, text, embedding, scope }));
             }
+            // Another agent's Star is private to it (CON-62).
+            const star = { level: 'agent', orgId: 'local', agentId: 'another-agent' };
+            await store.upsert(nodesGrant(star), memoryAt('other-agent', star, { agentId: 'another-agent' }, { text, embedding }));
             expect(ids(await store.lexical(localGrant(LOCAL), 'auth-service-8080', 10))).toEqual([
                 'mine',
             ]);
@@ -584,11 +586,31 @@ export function storeConformance(name, make) {
                 expect(await nonInterference(make, seed, 60, { multiNode: true })).toBeNull();
             }
         }, 120_000);
+        it(`isolation.non-interference-peer-agents-${seeds}-seeds`, async () => {
+            // CON-62: another agent of the same person, working in its own Star, never reaches mine.
+            for (let seed = 1; seed <= seeds; seed++) {
+                expect(await nonInterference(make, seed, 60, { peers: true })).toBeNull();
+            }
+        }, 120_000);
     });
     levelConformance(name, make);
 }
 /** The owner every level case belongs to or reads as: the local principal. */
 const OWNER = { orgId: 'local', customerId: 'self', agentId: 'claude-code' };
+/**
+ * The grant every local caller had before CON-62: the owner's Planet, restricted to memories its
+ * own agent wrote. Kept to prove data written before levels reads back unchanged.
+ */
+const PRE_LEVEL = nodeGrant({
+    principal: OWNER,
+    read: [
+        {
+            node: { level: 'user', orgId: 'local', customerId: 'self' },
+            projectIds: 'all',
+            authorAgentId: 'claude-code',
+        },
+    ],
+});
 const PROVENANCE = {
     derivedFrom: [{ vault: 'acct:1', memoryId: 'src-1' }],
     contributors: [
@@ -727,14 +749,38 @@ function levelConformance(name, make) {
         it('levels.pre-level-grants-see-no-other-level', async () => {
             for (const c of cases())
                 await store.upsert(c.g, c.m);
-            const legacy = [TG, localGrant({ ...OWNER, projectIds: ['p1', null] })];
-            for (const g of legacy) {
-                for (const c of cases())
-                    expect(await store.get(g, c.m.id), c.name).toBeNull();
-                expect(await store.list(g, { validOnly: false })).toEqual([]);
-                expect(await store.lexical(g, 'levelprobe', 50)).toEqual([]);
-                expect(await store.dense(g, vec(1, 1, -1, 2), 50)).toEqual([]);
+            for (const c of cases())
+                expect(await store.get(PRE_LEVEL, c.m.id), c.name).toBeNull();
+            expect(await store.list(PRE_LEVEL, { validOnly: false })).toEqual([]);
+            expect(await store.lexical(PRE_LEVEL, 'levelprobe', 50)).toEqual([]);
+            expect(await store.dense(PRE_LEVEL, vec(1, 1, -1, 2), 50)).toEqual([]);
+        });
+        it('levels.local-grants-see-the-planet-and-their-own-star', async () => {
+            // CON-62: a person's agents share the Planet; each agent's Star is its own.
+            for (const c of cases())
+                await store.upsert(c.g, c.m);
+            const ccStar = { level: 'agent', orgId: 'local', agentId: 'claude-code' };
+            await store.upsert(nodesGrant(ccStar), memoryAt('cc-star', ccStar, { agentId: 'claude-code' }, { text: 'levelprobe cc star' }));
+            const asClaude = [TG, localGrant({ ...OWNER, projectIds: ['p1', null] })];
+            for (const g of asClaude) {
+                expect(ids(await store.list(g, { validOnly: false })).sort()).toEqual([
+                    'cc-star',
+                    'lv-planet-other-author',
+                ]);
+                expect(ids(await store.lexical(g, 'levelprobe', 50)).sort()).toEqual([
+                    'cc-star',
+                    'lv-planet-other-author',
+                ]);
+                expect(await store.get(g, 'lv-star')).toBeNull();
+                expect(await store.setTier(g, 'lv-star', 'hot')).toBe(false);
             }
+            const asCursor = localGrant({ ...OWNER, agentId: 'cursor', projectIds: ['p1', null] });
+            expect(ids(await store.list(asCursor, { validOnly: false })).sort()).toEqual([
+                'lv-planet-other-author',
+                'lv-star',
+            ]);
+            expect(await store.get(asCursor, 'cc-star')).toBeNull();
+            expect(ids(await store.dense(asCursor, vec(2, 1, -1, 2), 50))).not.toContain('cc-star');
         });
         it('levels.existing-data-unchanged', async () => {
             const legacy = [
@@ -750,15 +796,16 @@ function levelConformance(name, make) {
             ];
             await store.upsertMany(TG, legacy);
             await seedCold(store, makeMemory({ id: 'old-4', text: 'levelprobe cold', embedding: vec(3, 1, -1, 2) }));
+            const g = PRE_LEVEL;
             const view = async () => {
                 const out = [];
                 for (const id of ['old-1', 'old-2', 'old-3', 'old-4']) {
-                    out.push(render(await store.get(TG, id)), render(await store.coldGet(TG, id)));
+                    out.push(render(await store.get(g, id)), render(await store.coldGet(g, id)));
                 }
-                out.push((await store.list(TG, { validOnly: false })).map(render).join('|'));
-                out.push(JSON.stringify(await store.dense(TG, vec(1, 1, -1, 2), 10)));
+                out.push((await store.list(g, { validOnly: false })).map(render).join('|'));
+                out.push(JSON.stringify(await store.dense(g, vec(1, 1, -1, 2), 10)));
                 // bm25 scores use table-wide statistics: compare which memories match.
-                out.push(ids(await store.lexical(TG, 'levelprobe orbit', 50))
+                out.push(ids(await store.lexical(g, 'levelprobe orbit', 50))
                     .sort()
                     .join(','));
                 return out;
@@ -846,7 +893,12 @@ function levelConformance(name, make) {
                 'by-cc',
                 'by-cursor',
             ]);
-            expect(ids(await store.lexical(TG, 'authorprobe', 10))).toEqual(['by-cc']);
+            expect(ids(await store.lexical(PRE_LEVEL, 'authorprobe', 10))).toEqual(['by-cc']);
+            // The local grant shares the Planet among the person's agents (CON-62).
+            expect(ids(await store.lexical(TG, 'authorprobe', 10)).sort()).toEqual([
+                'by-cc',
+                'by-cursor',
+            ]);
             const cursor = nodeGrant({
                 principal: { ...OWNER, agentId: 'cursor' },
                 read: [{ node: planet, projectIds: 'all', authorAgentId: 'cursor' }],
@@ -869,7 +921,8 @@ function levelConformance(name, make) {
                 read: [...TG.readNodes, { node: nodeOf(hive.address), projectIds: ['p1'] }],
                 write: TG.writeNodes,
             });
-            const visible = ['own', hive.m.id].sort();
+            const other = all.find((c) => c.name === 'planet-other-author');
+            const visible = ['own', other.m.id, hive.m.id].sort();
             expect(ids(await store.list(g, { validOnly: false })).sort()).toEqual(visible);
             expect(ids(await store.lexical(g, 'levelprobe', 50)).sort()).toEqual(visible);
             const dense = await store.dense(g, vec(9, 1, -1, 2), 50);
@@ -885,8 +938,8 @@ function levelConformance(name, make) {
             expect(await store.get(hive.g, hive.m.id)).not.toBeNull();
             await expect(store.upsert(g, memoryAt('new-hive', hive.address, hive.author))).rejects.toThrow(GrantError);
             // A project outside the pattern stays out.
-            const other = memoryAt('hive-p2', { ...hive.address, projectId: 'p2' }, hive.author);
-            await store.upsert(hive.g, other);
+            const hiveP2 = memoryAt('hive-p2', { ...hive.address, projectId: 'p2' }, hive.author);
+            await store.upsert(hive.g, hiveP2);
             expect(await store.get(g, 'hive-p2')).toBeNull();
         });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oortmem/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Oort core: the tiered hot, warm and cold memory engine for AI agents (types, scoring, recall, consolidation).",
   "keywords": [
     "oort",