@oortmem/core 0.2.1 → 0.4.0

package/dist/levels.js

@@ -0,0 +1,140 @@
+import { addressOf, authorOf, GALAXY_ROOT, nodeKey, nodeOf, spaceName, } from './address.js';
+import { readableNodes } from './grant.js';
+export const INCLUDE_LEVELS = Object.freeze([
+    'self',
+    'planet',
+    'star',
+    'constellation',
+    'galaxy',
+]);
+export const isIncludeLevel = (s) => INCLUDE_LEVELS.includes(s);
+/** At most this many hive nodes are read by default (spec 7.1: one recall, a bounded fan-out). */
+export const DEFAULT_HIVE_NODES = 4;
+/**
+ * A recall asked for a level its grant does not cover. Typed, so callers tell
+ * "you may not read that" apart from "nothing matched" (spec 7.1).
+ */
+export class ScopeDeniedError extends Error {
+    code = 'scope_denied';
+    levels;
+    constructor(levels) {
+        super(`scope_denied: this grant cannot read ${levels.join(', ')}`);
+        this.name = 'ScopeDeniedError';
+        this.levels = levels;
+    }
+}
+/** True when `node` is what `level` names for a caller whose grant is `g`. */
+function names(level, node, g) {
+    switch (level) {
+        case 'self':
+            return nodeKey(node) === nodeKey(g.home);
+        case 'planet':
+            return node.level === 'user';
+        case 'star':
+            return (node.level === 'agent' &&
+                node.orgId === g.principal.orgId &&
+                node.agentId === g.principal.agentId);
+        case 'constellation':
+            return node.level === 'hive' && node.hiveId !== GALAXY_ROOT;
+        case 'galaxy':
+            return node.level === 'hive' && node.hiveId === GALAXY_ROOT;
+    }
+}
+/**
+ * The nodes one recall reads: with `include`, every readable node a named
+ * level covers (a level that covers none rejects with `ScopeDeniedError`);
+ * without it, every readable node, hive nodes capped at `DEFAULT_HIVE_NODES`
+ * in grant order. Never a node outside `g`.
+ */
+export function nodesToRead(g, include) {
+    const readable = readableNodes(g);
+    if (include === undefined || include.length === 0) {
+        let hives = 0;
+        return readable.filter((n) => n.level !== 'hive' || ++hives <= DEFAULT_HIVE_NODES);
+    }
+    for (const l of include) {
+        if (!isIncludeLevel(l))
+            throw new RangeError(`unknown level ${JSON.stringify(l)}`);
+    }
+    const denied = [...new Set(include)].filter((l) => !readable.some((n) => names(l, n, g)));
+    if (denied.length > 0)
+        throw new ScopeDeniedError(denied);
+    return readable.filter((n) => include.some((l) => names(l, n, g)));
+}
+/**
+ * How specific a node is, for the specificity prior and the conflict rule:
+ * an agent's own memory (Star, Orbit, Flyby) 3, the person's Planet 2, a
+ * Constellation 1, a Galaxy 0. Narrower is higher.
+ */
+export function specificity(node) {
+    switch (node.level) {
+        case 'agent':
+        case 'agent-user':
+        case 'run':
+            return 3;
+        case 'user':
+            return 2;
+        case 'hive':
+            return node.hiveId === GALAXY_ROOT ? 0 : 1;
+    }
+}
+/**
+ * The specificity prior's factor for a node: `1 + ε × specificity / 3`, so
+ * with `ε` the narrowest level gains `ε` and a Galaxy nothing. `ε = 0` (the
+ * default) leaves every score as it was.
+ */
+export function specificityFactor(node, epsilon) {
+    return 1 + (epsilon * specificity(node)) / 3;
+}
+/** Brackets in memory text, escaped so the text cannot pass for a code-built label. */
+export function escapeLabelText(text) {
+    return text.replace(/[[\]]/g, (c) => `\\${c}`);
+}
+/** An id shown inside a label: control characters dropped, brackets escaped, clipped. */
+function labelId(id) {
+    // oxlint-disable-next-line no-control-regex
+    const clean = escapeLabelText(id.replace(/[\u0000-\u001f\u007f]/g, ''));
+    return clean.length > 40 ? `${clean.slice(0, 39)}…` : clean;
+}
+/** The node part of a label for `node`, as the caller of grant `g` sees it. */
+export function nodeLabel(node, g) {
+    switch (node.level) {
+        case 'user':
+            return node.orgId === g.principal.orgId && node.customerId === g.principal.customerId
+                ? 'your Planet'
+                : 'a Planet';
+        case 'agent':
+            return `Star ${labelId(node.agentId)}`;
+        case 'agent-user':
+            return `Orbit ${labelId(node.agentId)}`;
+        case 'run':
+            return `Flyby ${labelId(node.runId)}`;
+        case 'hive':
+            return node.hiveId === GALAXY_ROOT ? 'Galaxy' : `Constellation ${labelId(node.hiveId)}`;
+    }
+}
+/** The origin of `m` for the caller of grant `g`. */
+export function originOf(m, g) {
+    const node = nodeOf(addressOf(m));
+    const label = nodeLabel(node, g);
+    const ownStar = node.level === 'agent' &&
+        node.orgId === g.principal.orgId &&
+        node.agentId === g.principal.agentId;
+    return {
+        level: node.level,
+        space: spaceName(node),
+        node: label,
+        from: ownStar ? "from this agent's Star" : `from ${label}`,
+        home: nodeKey(node) === nodeKey(g.home),
+        author: authorOf(m).agentId,
+    };
+}
+/** The decision `observe` records on a memory written instead of editing one in another node. */
+export const CONTRADICTS = { stage: 'level', question: 'contradicts' };
+/** The ids of memories in other nodes that `m` contradicts (recorded by `observe`). */
+export function contradicted(m) {
+    return m.source.decisions
+        .filter((d) => d.stage === CONTRADICTS.stage && d.question === CONTRADICTS.question)
+        .map((d) => d.answer);
+}
+//# sourceMappingURL=levels.js.map

package/dist/memory-store.js

@@ -1,5 +1,6 @@
 import { appendAccess } from './activation.js';
-import { assertGrant, canRead, canWrite, cursorKey, filterCovers, GrantError, sameScope, } from './grant.js';
+import { canonicalMemory } from './address.js';
+import { assertGrant, cursorKey, grantReads, grantWrites, GrantError, sameRecordAddress, } from './grant.js';
 import { isCurrent } from './model.js';
 import { tokenizeLexical as tokens } from './tokenize.js';
 function cosine(a, b) {
@@ -46,26 +47,32 @@ export function createMemoryStore(opts = {}) {
         if (m.tier !== 'cold')
             cold.delete(m.id);
     }
-    function scoped(f) {
-        return [...main.values()].filter((m) => filterCovers(f, m.scope));
+    function scoped(grant) {
+        return [...main.values()].filter((m) => grantReads(grant, m));
     }
     /** The live record if `grant` may read it; `undefined` for unknown and out-of-grant alike. */
     function readable(grant, id) {
         const m = main.get(id);
-        return m !== undefined && canRead(grant, m.scope) ? m : undefined;
+        return m !== undefined && grantReads(grant, m) ? m : undefined;
     }
     /** The live record if `grant` may change it. */
     function writable(grant, id) {
         const m = main.get(id);
-        return m !== undefined && canWrite(grant, m.scope) ? m : undefined;
+        return m !== undefined && grantWrites(grant, m) ? m : undefined;
     }
-    /** Every check `upsert` makes, before anything is written. */
-    function checkWrite(grant, m) {
-        if (!canWrite(grant, m.scope))
+    /**
+     * Every check `upsert` makes, before anything is written: a legal address
+     * that matches the scope (`RangeError` otherwise), inside `grant.write`,
+     * and the same address, author and scope as any record already under the id.
+     * Returns the record as stored.
+     */
+    function checkWrite(grant, m, existing) {
+        const c = canonicalMemory(m);
+        if (!grantWrites(grant, c))
             throw new GrantError();
-        const existing = main.get(m.id);
-        if (existing !== undefined && !sameScope(existing.scope, m.scope))
+        if (existing !== undefined && !sameRecordAddress(existing, c))
             throw new GrantError();
+        return c;
     }
     /** True while the live record still matches the snapshot a guarded write was computed from. */
     function unchanged(live, snap) {
@@ -116,8 +123,7 @@ export function createMemoryStore(opts = {}) {
             open();
             assertGrant(grant);
             const c = structuredClone(m);
-            checkWrite(grant, c);
-            put(c);
+            put(checkWrite(grant, c, main.get(c.id)));
         },
         /** Atomic trivially: checks and clones every record before writing any. */
         async upsertMany(grant, ms) {
@@ -127,15 +133,13 @@ export function createMemoryStore(opts = {}) {
             // Later entries may move an id the batch itself created: check against
             // the batch's own earlier entries as well as the store.
             const batch = new Map();
+            const checked = [];
             for (const c of cs) {
-                if (!canWrite(grant, c.scope))
-                    throw new GrantError();
-                const existing = batch.get(c.id) ?? main.get(c.id);
-                if (existing !== undefined && !sameScope(existing.scope, c.scope))
-                    throw new GrantError();
-                batch.set(c.id, c);
+                const ok = checkWrite(grant, c, batch.get(c.id) ?? main.get(c.id));
+                batch.set(c.id, ok);
+                checked.push(ok);
             }
-            for (const c of cs)
+            for (const c of checked)
                 put(c);
         },
         async get(grant, id) {
@@ -164,7 +168,7 @@ export function createMemoryStore(opts = {}) {
             if (query.size === 0)
                 return [];
             const scored = [];
-            for (const m of scoped(grant.read)) {
+            for (const m of scoped(grant)) {
                 const fields = m.tier === 'cold' ? [m.stub, ...m.entities] : [m.text, m.stub, ...m.entities];
                 const doc = new Set(tokens(fields.join(' ')));
                 let score = 0;
@@ -180,7 +184,7 @@ export function createMemoryStore(opts = {}) {
             open();
             assertGrant(grant);
             const scored = [];
-            for (const m of scoped(grant.read)) {
+            for (const m of scoped(grant)) {
                 if (m.tier === 'cold' || m.embedding === undefined)
                     continue;
                 if (m.embedding.length !== v.length) {
@@ -204,7 +208,7 @@ export function createMemoryStore(opts = {}) {
             assertGrant(grant);
             const validOnly = listOpts.validOnly ?? true;
             const now = clock();
-            return scoped(grant.read)
+            return scoped(grant)
                 .filter((m) => !validOnly || isCurrent(m, now))
                 .filter((m) => listOpts.tier === undefined || m.tier === listOpts.tier)
                 .filter((m) => listOpts.pinned !== true || m.pinned)
@@ -225,7 +229,7 @@ export function createMemoryStore(opts = {}) {
             if (readable(grant, id) === undefined)
                 return null;
             const m = cold.get(id);
-            return m === undefined || !canRead(grant, m.scope) ? null : structuredClone(m);
+            return m === undefined || !grantReads(grant, m) ? null : structuredClone(m);
         },
         async setTier(grant, id, tier, snapshot) {
             open();

package/dist/model.d.ts

@@ -1,5 +1,12 @@
+import type { Address, Author, Provenance } from './address.js';
 export type MemoryType = 'semantic' | 'episodic' | 'procedural' | 'preference';
 export type Tier = 'hot' | 'warm' | 'cold';
+/**
+ * The pre-level view of where a memory lives. For a Planet memory (every
+ * memory written before levels) it is the whole story: the Planet is
+ * (org, customer, project) and `agentId` is the author. For other levels see
+ * `scopeOf` in `address.ts`. Grants are checked against `address` and `author`.
+ */
 export interface Scope {
     orgId: string;
     customerId: string;
@@ -38,6 +45,16 @@ export interface MemorySource {
 export interface Memory {
     id: string;
     scope: Scope;
+    /**
+     * Where the memory lives. Absent: the Planet `scope` names, which is where
+     * every memory written before levels lives, so stores return it only for
+     * other levels. Read it with `addressOf(m)`.
+     */
+    address?: Address;
+    /** Who wrote it. Absent: the agent `scope.agentId` names. Read it with `authorOf(m)`. */
+    author?: Author;
+    /** Where a shared copy came from; absent (or null) on ordinary memories. */
+    provenance?: Provenance | null;
     type: MemoryType;
     text: string;
     stub: string;

package/dist/observe.d.ts

@@ -1,5 +1,6 @@
 import type { DecisionController, Embedder, MemoryStore, MemoryWriter, Observation } from './adapters.js';
 import type { ResolvedConfig } from './config.js';
+import { type Home } from './grant.js';
 import type { Decision, Scope } from './model.js';
 export type MemoryOutcomeKind = 'skipped' | 'reinforced' | 'added' | 'updated' | 'superseded' | 'corrected';
 /** What happened to one memory the turn produced. */
@@ -29,6 +30,14 @@ export interface ObserveDeps {
     now?: Date;
     /** Recorded on `source.harness`; defaults to "unknown". */
     harness?: string;
+    /**
+     * Where new memories land (spec 5.1): the person's Planet (default) or, for an agent configured
+     * as a Star, `scope.agentId`'s own Star. Candidates come from both. A memory is only ever
+     * superseded, corrected or refined in the home node, and an agent whose home is its Star never
+     * writes the Planet at all: a Planet memory it re-observes gets an access record (activation),
+     * never a confirmation or an edit.
+     */
+    home?: Home;
 }
 /**
  * Gate-stage reinforcement match floor. When the gate says "do not store", a

package/dist/observe.js

@@ -1,5 +1,7 @@
 import { randomUUID } from 'node:crypto';
-import { localGrant } from './grant.js';
+import { addressed, addressOf, nodeKey, nodeOf } from './address.js';
+import { grantWrites, homeAddress, localGrant } from './grant.js';
+import { CONTRADICTS } from './levels.js';
 import { capObservation } from './cap.js';
 import { scrubObservation } from './scrub.js';
 import { checkWriterDate, factInterval, utcOffset } from './temporal.js';
@@ -125,11 +127,30 @@ async function apply(a) {
         if (target === undefined)
             return { outcome: 'skipped' };
         await store.recordAccess(grant, [target.id], now);
-        await confirm(store, grant, target.id, now.toISOString());
+        // Confirming writes the memory: only where this agent may write (a Star agent reinforces a
+        // Planet memory's activation but never edits it).
+        if (grantWrites(grant, target))
+            await confirm(store, grant, target.id, now.toISOString());
         return { outcome: 'reinforced', memoryId: target.id };
     }
     let action = best.action === 'UPDATE' ? 'REFINE' : best.action;
     let prior = action === 'ADD' ? undefined : candidates.find((c) => c.id === best.candidateId);
+    if (prior !== undefined && nodeKey(nodeOf(addressOf(prior))) !== nodeKey(grant.home)) {
+        // The prior lives in another node (the Planet, for an agent writing to its Star, or the
+        // reverse). A write never edits a memory outside its home node: the observation becomes a
+        // memory of its own there. A contradiction is recorded, so recall can rank the narrower of the
+        // two first and label the other (spec 7.2). Reinforcing it (above) stays allowed.
+        decisions.push({
+            stage: 'level',
+            question: 'other-node',
+            answer: 'add-instead',
+            probability: 1,
+        });
+        if (action === 'SUPERSEDE' || action === 'CORRECT') {
+            decisions.push({ ...CONTRADICTS, answer: prior.id, probability: best.probability });
+        }
+        prior = undefined;
+    }
     if (prior !== undefined && (prior.scope.projectId ?? null) !== (scope.projectId ?? null)) {
         // Candidates include global memories. A project's observation must not end or
         // rewrite a fact another scope (every project, for a global one) relies on, so it
@@ -235,6 +256,9 @@ async function apply(a) {
     const base = {
         id,
         scope,
+        // A memory at another level than the Planet carries its address and author.
+        ...(grant.home.level !== 'user' &&
+            addressed(homeAddress(grant, scope.projectId), { agentId: scope.agentId })),
         type: w.type,
         text: w.text,
         stub: w.stub,
@@ -418,7 +442,7 @@ export async function observe(raw, scope, deps) {
     const obs = capObservation(scrubbed.obs);
     const { store, embed, decide, write } = deps;
     const now = deps.now ?? new Date();
-    const grant = localGrant(filterFor(scope));
+    const grant = localGrant(filterFor(scope), deps.home === undefined ? {} : { home: deps.home });
     const g = await decide.gate(obs);
     const text = `${obs.userText}\n${obs.assistantText}`;
     if (g.shouldStore < GATE_THRESHOLD) {

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;