@oortmem/core 0.3.0 → 0.5.0

package/dist/agents.d.ts

@@ -0,0 +1,38 @@
+import { ANONYMOUS_AGENT, type Home } from './grant.js';
+/**
+ * Agent identities on one machine (CON-62). Every host Oort is connected to
+ * acts as its own agent (`claude-code`, `codex`, `cursor`, …): they share the
+ * person's Planet, and each has a Star of its own that no other agent reads.
+ * An agent configured as a Star (`oort connect cursor --star`) writes new
+ * memories to its Star instead of the Planet. The configuration lives in
+ * `$OORT_HOME/agents.json` (0600).
+ */
+/**
+ * Claude Code's agent id: what every local memory before agents was written as, and what the
+ * Claude Code hooks and transcript import always act as. A caller that names no agent is
+ * `ANONYMOUS_AGENT` (Planet only), never this.
+ */
+export declare const DEFAULT_AGENT = "claude-code";
+export { ANONYMOUS_AGENT };
+/** Agents configured as Stars, under `OORT_HOME`. */
+export declare const AGENTS_FILE = "agents.json";
+/** A lowercase id: letters, digits, `.`, `_` and `-`, at most 64 characters, starting alphanumeric. */
+export declare const AGENT_ID: RegExp;
+/** A valid agent id that is not reserved (`anonymous` names a caller that named none). */
+export declare const isAgentId: (s: string) => boolean;
+export interface AgentSettings {
+    /** New memories land in this agent's Star (private to it) instead of the person's Planet. */
+    star: boolean;
+}
+/**
+ * The agents configured in `home`. A missing or unreadable file means none,
+ * so every agent writes to the Planet (as before agents existed).
+ */
+export declare function readAgents(home: string): Record<string, AgentSettings>;
+/**
+ * Records whether agent `id` keeps a Star (0600). Returns true when that changed anything. An agent
+ * that stops keeping one stays listed (`star: false`), so its Star is still found (export).
+ */
+export declare function setAgentStar(home: string, id: string, star: boolean): boolean;
+/** Where agent `id`'s new memories land. */
+export declare function agentHome(home: string, id: string): Home;

package/dist/agents.js

@@ -0,0 +1,67 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ANONYMOUS_AGENT } from './grant.js';
+import { writePrivateFile } from './private-fs.js';
+/**
+ * Agent identities on one machine (CON-62). Every host Oort is connected to
+ * acts as its own agent (`claude-code`, `codex`, `cursor`, …): they share the
+ * person's Planet, and each has a Star of its own that no other agent reads.
+ * An agent configured as a Star (`oort connect cursor --star`) writes new
+ * memories to its Star instead of the Planet. The configuration lives in
+ * `$OORT_HOME/agents.json` (0600).
+ */
+/**
+ * Claude Code's agent id: what every local memory before agents was written as, and what the
+ * Claude Code hooks and transcript import always act as. A caller that names no agent is
+ * `ANONYMOUS_AGENT` (Planet only), never this.
+ */
+export const DEFAULT_AGENT = 'claude-code';
+export { ANONYMOUS_AGENT };
+/** Agents configured as Stars, under `OORT_HOME`. */
+export const AGENTS_FILE = 'agents.json';
+/** A lowercase id: letters, digits, `.`, `_` and `-`, at most 64 characters, starting alphanumeric. */
+export const AGENT_ID = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/** A valid agent id that is not reserved (`anonymous` names a caller that named none). */
+export const isAgentId = (s) => AGENT_ID.test(s) && s !== ANONYMOUS_AGENT;
+/**
+ * The agents configured in `home`. A missing or unreadable file means none,
+ * so every agent writes to the Planet (as before agents existed).
+ */
+export function readAgents(home) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(path.join(home, AGENTS_FILE), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+    const agents = parsed?.agents;
+    if (typeof agents !== 'object' || agents === null || Array.isArray(agents))
+        return {};
+    const out = {};
+    for (const [id, v] of Object.entries(agents)) {
+        if (!isAgentId(id) || typeof v !== 'object' || v === null)
+            continue;
+        out[id] = { star: v.star === true };
+    }
+    return out;
+}
+/**
+ * Records whether agent `id` keeps a Star (0600). Returns true when that changed anything. An agent
+ * that stops keeping one stays listed (`star: false`), so its Star is still found (export).
+ */
+export function setAgentStar(home, id, star) {
+    if (!isAgentId(id))
+        throw new RangeError(`not an agent id: ${JSON.stringify(id)}`);
+    const agents = readAgents(home);
+    if ((agents[id]?.star ?? false) === star)
+        return false;
+    agents[id] = { star };
+    writePrivateFile(path.join(home, AGENTS_FILE), `${JSON.stringify({ version: 1, agents }, null, 2)}\n`);
+    return true;
+}
+/** Where agent `id`'s new memories land. */
+export function agentHome(home, id) {
+    return readAgents(home)[id]?.star === true ? 'star' : 'planet';
+}
+//# sourceMappingURL=agents.js.map

package/dist/config.d.ts

@@ -42,6 +42,7 @@ export declare const OortConfig: z.ZodObject<{
         rerankBudgetMs: z.ZodDefault<z.ZodNumber>;
         queryCacheTtlSec: z.ZodDefault<z.ZodNumber>;
         staleAfterDays: z.ZodDefault<z.ZodNumber>;
+        specificityPrior: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>;
     project: z.ZodDefault<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;

package/dist/config.js

@@ -69,6 +69,12 @@ const recall = z
      * marked "may be outdated" when injected, and listed by `oort revalidate`. 0 turns it off.
      */
     staleAfterDays: z.number().int().min(0).default(30),
+    /**
+     * The specificity prior ε (spec 7.2): when a recall reads several nodes, each fused score is
+     * scaled by 1 + ε × specificity / 3 (an agent's Star 3, the Planet 2, a Constellation 1, a
+     * Galaxy 0). 0, the default, turns it off: it is turned on only if the eval shows a gain.
+     */
+    specificityPrior: z.number().min(0).max(1).default(0),
 })
     .default({
     lexicalK: 50,
@@ -84,6 +90,7 @@ const recall = z
     rerankBudgetMs: 400,
     queryCacheTtlSec: 600,
     staleAfterDays: 30,
+    specificityPrior: 0,
 });
 const project = z
     .strictObject({

package/dist/consolidate.d.ts

@@ -1,5 +1,6 @@
 import type { MemoryStore, ScopeFilter } from './adapters.js';
 import type { ResolvedConfig } from './config.js';
+import { type Grant } from './grant.js';
 export interface ConsolidateResult {
     /** Ids whose tier moved up (warm to hot). */
     promoted: string[];
@@ -15,6 +16,24 @@ export interface ConsolidateResult {
      * The record is left as the other writer made it; the next run reconsiders it.
      */
     skipped: number;
+    /**
+     * False when `shouldStop` cut the run short. Every write made so far stands (each is atomic and
+     * guarded), and a later run picks up the rest: consolidation recomputes everything from the
+     * store, so nothing is lost by stopping between two writes.
+     */
+    complete: boolean;
+}
+export interface ConsolidateDeps {
+    store: MemoryStore;
+    config: ResolvedConfig;
+    now?: Date;
+    /**
+     * Checked before each store call that lists or writes: once it returns true, consolidation
+     * starts nothing new and resolves with `complete: false`. A time budget (the hook drain's).
+     */
+    shouldStop?: () => boolean;
+    /** Evictions per `coldPutMany` call (default `COLD_EVICT_BATCH`); smaller holds the write lock for less. */
+    evictBatch?: number;
 }
 /** Evictions per `coldPutMany` call: one store transaction and one directory sync each. */
 export declare const COLD_EVICT_BATCH = 500;
@@ -24,8 +43,10 @@ export declare const COLD_EVICT_BATCH = 500;
  *    `expiredAt = now`, `endReason = endReason ?? "expired"` (`expireMany`).
  * 2. Rank current memories by ACT-R activation (ties: newer `updatedAt`
  *    first) and assign tiers via `tierFor`; changes are `setTier`d and new
- *    cold memories are collected and `coldPutMany`'d in batches of `COLD_EVICT_BATCH`.
- * 3. Non-current memories (superseded, expired, corrected) go straight to cold.
+ *    cold memories are collected and `coldPutMany`'d in batches of `COLD_EVICT_BATCH`
+ *    (each read whole first, since the listing leaves embeddings out).
+ * 3. Non-current memories (superseded, expired, corrected) go straight to cold
+ *    (evicted ahead of the stale current ones).
  *
  * Every write is targeted (expiry writes only the expiry fields, a tier change
  * only the tier, an eviction only the tier and the cold copy) and guarded by
@@ -37,9 +58,17 @@ export declare const COLD_EVICT_BATCH = 500;
  * left in its current tier (hot or warm); consolidate never promotes cold to warm/hot, since
  * hydration is recall's job.
  * Idempotent for a fixed `now`.
+ *
+ * Each node the scope's grant covers (the person's Planet, this agent's Star)
+ * is consolidated on its own, so the Planet's tiers do not depend on which of
+ * the person's agents ran consolidation. Inside a node each project, and the
+ * global memories (no project), is ranked on its own (`hotTopN` per project),
+ * so a global memory's tier does not depend on which project ran it (CON-48).
  */
-export declare function consolidate(scope: ScopeFilter, deps: {
-    store: MemoryStore;
-    config: ResolvedConfig;
-    now?: Date;
-}): Promise<ConsolidateResult>;
+export declare function consolidate(scope: ScopeFilter, deps: ConsolidateDeps): Promise<ConsolidateResult>;
+/**
+ * `consolidate` over every node `grant` both reads and writes: a Star agent's grant reads the
+ * Planet but does not write it, so the Planet is left alone. With `principalGrant` it covers every
+ * project of the person, which is what the hook drain runs.
+ */
+export declare function consolidateGrant(grant: Grant, deps: ConsolidateDeps): Promise<ConsolidateResult>;

package/dist/consolidate.js

@@ -1,17 +1,21 @@
 import { activation, tierFor } from './activation.js';
-import { localGrant } from './grant.js';
+import { addressOf, nodeKey } from './address.js';
+import { assertGrant, localGrant, narrowGrant, readableNodes } from './grant.js';
 import { isCurrent } from './model.js';
 /** Evictions per `coldPutMany` call: one store transaction and one directory sync each. */
 export const COLD_EVICT_BATCH = 500;
 const RANK = { cold: 0, warm: 1, hot: 2 };
+const LISTING = { validOnly: false, embeddings: false };
 /**
  * Background consolidation. In order:
  * 1. Expire: memories with `validTo <= now` and no `expiredAt` get
  *    `expiredAt = now`, `endReason = endReason ?? "expired"` (`expireMany`).
  * 2. Rank current memories by ACT-R activation (ties: newer `updatedAt`
  *    first) and assign tiers via `tierFor`; changes are `setTier`d and new
- *    cold memories are collected and `coldPutMany`'d in batches of `COLD_EVICT_BATCH`.
- * 3. Non-current memories (superseded, expired, corrected) go straight to cold.
+ *    cold memories are collected and `coldPutMany`'d in batches of `COLD_EVICT_BATCH`
+ *    (each read whole first, since the listing leaves embeddings out).
+ * 3. Non-current memories (superseded, expired, corrected) go straight to cold
+ *    (evicted ahead of the stale current ones).
  *
  * Every write is targeted (expiry writes only the expiry fields, a tier change
  * only the tier, an eviction only the tier and the cold copy) and guarded by
@@ -23,65 +27,135 @@ const RANK = { cold: 0, warm: 1, hot: 2 };
  * left in its current tier (hot or warm); consolidate never promotes cold to warm/hot, since
  * hydration is recall's job.
  * Idempotent for a fixed `now`.
+ *
+ * Each node the scope's grant covers (the person's Planet, this agent's Star)
+ * is consolidated on its own, so the Planet's tiers do not depend on which of
+ * the person's agents ran consolidation. Inside a node each project, and the
+ * global memories (no project), is ranked on its own (`hotTopN` per project),
+ * so a global memory's tier does not depend on which project ran it (CON-48).
  */
 export async function consolidate(scope, deps) {
+    return consolidateGrant(localGrant(scope), deps);
+}
+/**
+ * `consolidate` over every node `grant` both reads and writes: a Star agent's grant reads the
+ * Planet but does not write it, so the Planet is left alone. With `principalGrant` it covers every
+ * project of the person, which is what the hook drain runs.
+ */
+export async function consolidateGrant(grant, deps) {
+    assertGrant(grant);
     const { store, config } = deps;
-    const grant = localGrant(scope);
     const now = deps.now ?? new Date();
+    const run = {
+        store,
+        config,
+        now,
+        stop: deps.shouldStop ?? (() => false),
+        evictBatch: Math.max(1, deps.evictBatch ?? COLD_EVICT_BATCH),
+    };
     const result = {
         promoted: [],
         demoted: [],
         evicted: [],
         expired: [],
         skipped: 0,
+        complete: true,
     };
+    const writable = new Set(grant.writeNodes.map((p) => nodeKey(p.node)));
+    for (const node of readableNodes(grant).filter((n) => writable.has(nodeKey(n)))) {
+        if (!(await consolidateNode(run, narrowGrant(grant, [node]), result))) {
+            result.complete = false;
+            break;
+        }
+    }
+    return result;
+}
+/** A memory's project inside its node (`null`: global). */
+const projectOf = (m) => addressOf(m).projectId ?? null;
+/** One node; false when `run.stop` cut it short. */
+async function consolidateNode(run, grant, result) {
+    const { store, config, now } = run;
+    if (run.stop())
+        return false;
+    // One listing serves every step (a second one only after expiry changed records). Embeddings are
+    // read only for the memories evicted (a fraction of the cost of listing them all).
+    let all = await store.list(grant, LISTING);
     // 1. Expire.
-    const due = (await store.list(grant, { validOnly: false })).filter((m) => m.validTo !== null && m.expiredAt === null && Date.parse(m.validTo) <= now.getTime());
+    const due = all.filter((m) => m.validTo !== null && m.expiredAt === null && Date.parse(m.validTo) <= now.getTime());
     if (due.length > 0) {
+        if (run.stop())
+            return false;
         const skipped = new Set((await store.expireMany(grant, due, now)).skipped);
         for (const m of due)
             if (!skipped.has(m.id))
                 result.expired.push(m.id);
         result.skipped += skipped.size;
+        if (run.stop())
+            return false;
+        all = await store.list(grant, LISTING);
     }
-    // 2. Rank and assign current memories.
-    const current = (await store.list(grant, { validOnly: true })).filter((m) => isCurrent(m, now));
-    const scored = current.map((m) => ({
-        m,
-        a: activation(m.accessLog, m.salience, now, config.activation),
-    }));
-    scored.sort((x, y) => y.a - x.a || (x.m.updatedAt < y.m.updatedAt ? 1 : x.m.updatedAt > y.m.updatedAt ? -1 : 0));
+    // 2. Rank and assign current memories, each project (and global) on its own.
+    const current = all.filter((m) => isCurrent(m, now));
     const currentIds = new Set(current.map((m) => m.id));
-    const evictions = [];
-    for (const [rank, { m, a }] of scored.entries()) {
-        const target = tierFor(a, rank, m.pinned, config.activation);
-        if (target === m.tier)
-            continue;
-        if (m.tier === 'cold')
-            continue; // never promote out of cold here
-        if (target === 'cold') {
-            evictions.push(m);
-        }
-        else if (await store.setTier(grant, m.id, target, m)) {
-            (RANK[target] > RANK[m.tier] ? result.promoted : result.demoted).push(m.id);
-        }
-        else {
-            result.skipped++;
-        }
+    const byProject = new Map();
+    for (const m of current) {
+        const key = projectOf(m);
+        const list = byProject.get(key);
+        if (list === undefined)
+            byProject.set(key, [m]);
+        else
+            list.push(m);
     }
-    // 3. Non-current memories go straight to cold (unless pinned or already cold).
-    for (const m of await store.list(grant, { validOnly: false })) {
-        if (currentIds.has(m.id) || m.pinned || m.tier === 'cold')
-            continue;
-        evictions.push(m);
+    // 3 first. Non-current memories (superseded, expired) go straight to cold, unless pinned or
+    // already cold; they lead the evictions, so a run cut short has moved them first.
+    const evictions = all.filter((m) => !currentIds.has(m.id) && !m.pinned && m.tier !== 'cold');
+    for (const members of byProject.values()) {
+        const scored = members.map((m) => ({
+            m,
+            a: activation(m.accessLog, m.salience, now, config.activation),
+        }));
+        scored.sort((x, y) => y.a - x.a || (x.m.updatedAt < y.m.updatedAt ? 1 : x.m.updatedAt > y.m.updatedAt ? -1 : 0));
+        for (const [rank, { m, a }] of scored.entries()) {
+            const target = tierFor(a, rank, m.pinned, config.activation);
+            if (target === m.tier)
+                continue;
+            if (m.tier === 'cold')
+                continue; // never promote out of cold here
+            if (target === 'cold') {
+                evictions.push(m);
+                continue;
+            }
+            if (run.stop())
+                return false;
+            if (await store.setTier(grant, m.id, target, m)) {
+                (RANK[target] > RANK[m.tier] ? result.promoted : result.demoted).push(m.id);
+            }
+            else {
+                result.skipped++;
+            }
+        }
     }
-    await evictAll(store, grant, evictions, result);
-    return result;
+    return evictAll(run, grant, evictions, result);
 }
-async function evictAll(store, grant, evictions, result) {
-    for (let i = 0; i < evictions.length; i += COLD_EVICT_BATCH) {
-        const batch = evictions.slice(i, i + COLD_EVICT_BATCH);
-        // Each entry is the snapshot it was chosen from: the store's guard checks it.
+async function evictAll(run, grant, evictions, result) {
+    const { store } = run;
+    for (let i = 0; i < evictions.length; i += run.evictBatch) {
+        if (run.stop())
+            return false;
+        // The cold copy keeps the embedding the listing left out: read each record whole, and drop
+        // any that changed since it was chosen. The store's guard checks the rest at commit.
+        const batch = [];
+        for (const chosen of evictions.slice(i, i + run.evictBatch)) {
+            const whole = await store.get(grant, chosen.id);
+            if (whole !== null && whole.updatedAt === chosen.updatedAt && whole.tier === chosen.tier) {
+                batch.push(whole);
+            }
+            else {
+                result.skipped++;
+            }
+        }
+        if (batch.length === 0)
+            continue;
         const skipped = new Set((await store.coldPutMany(grant, batch)).skipped);
         for (const m of batch) {
             if (skipped.has(m.id))
@@ -91,5 +165,6 @@ async function evictAll(store, grant, evictions, result) {
         }
         result.skipped += skipped.size;
     }
+    return true;
 }
 //# sourceMappingURL=consolidate.js.map

package/dist/grant.d.ts

@@ -27,15 +27,26 @@ export interface GrantFilter extends Readonly<Principal> {
  * One node a grant covers (CON-61): the node, the project bindings inside it,
  * and optionally one author. Matching is structural and exact on every field
  * (never a prefix). `authorAgentId` restricts the pattern to memories that
- * agent wrote; the pre-level constructors (`localGrant`, `principalGrant`)
- * set it to the principal's agent, so they see exactly what they saw before
- * levels existed.
+ * agent wrote. The local constructors (`localGrant`, `principalGrant`) name
+ * the principal's Planet with no author restriction (a person's agents share
+ * their Planet, CON-62) and the principal's agent's own Star.
  */
 export interface NodePattern {
     readonly node: NodeRef;
     readonly projectIds: GrantProjects;
     readonly authorAgentId?: string;
 }
+/**
+ * Where an agent's new memories land by default (its home node, spec 5.1):
+ * the person's Planet, or the agent's own Star when it is configured as one.
+ */
+export type Home = 'planet' | 'star';
+/**
+ * The agent id of a caller that named no agent (an MCP entry written before agents existed, a
+ * terminal without `--agent`). It reads and writes the person's Planet only: it has no Star, so
+ * it can neither see nor create one. No configured agent may use this id.
+ */
+export declare const ANONYMOUS_AGENT = "anonymous";
 /**
  * The permission every `MemoryStore` method takes. Opaque: built only by
  * `localGrant`, `principalGrant` or `nodeGrant`, frozen, and nominal, so a raw
@@ -58,24 +69,48 @@ export declare class Grant {
     readonly write: GrantFilter;
     readonly readNodes: readonly NodePattern[];
     readonly writeNodes: readonly NodePattern[];
+    /**
+     * The node new memories are written to (the home node): the principal's
+     * Planet unless the agent keeps a Star. Engine code that creates a memory
+     * (observe, remember) addresses it here; edits of existing memories keep
+     * their own address. Covered by `writeNodes` whenever they are not empty.
+     */
+    readonly home: NodeRef;
     private constructor();
     /** @internal Use `localGrant` or `principalGrant`. */
-    static issue(principal: Principal, read: GrantProjects, write: GrantProjects): Grant;
-    /** @internal Use `nodeGrant`. */
-    static issueNodes(principal: Principal, read: readonly NodePattern[], write: readonly NodePattern[]): Grant;
+    static issue(principal: Principal, read: GrantProjects, write: GrantProjects, home?: Home): Grant;
+    /** @internal Use `nodeGrant` or `narrowGrant`. */
+    static issueNodes(principal: Principal, read: readonly NodePattern[], write: readonly NodePattern[], home?: NodeRef): Grant;
     /** True for a real grant (not a copy, not a look-alike). */
     static is(x: unknown): x is Grant;
 }
+/** The Star of a principal's agent (owned by the principal's owner). */
+export declare function starNode(p: Pick<Principal, 'orgId' | 'agentId'>): NodeRef;
 /**
- * The grant for today's single-principal callers: read exactly what `read`
- * names (a one-node grant), and write the same unless `opts.write` narrows it.
- * `write` must name the same principal as `read`.
+ * The grant for one agent of one person (CON-62): read and write the
+ * person's Planet (memories any of their agents wrote) and this agent's own
+ * Star, in the projects `read` names; `opts.write` may narrow the write side.
+ * Another agent's Star is never covered. `opts.home` picks where new memories
+ * land: the Planet (default) or the agent's Star; with `star` the Planet is
+ * read-only (the agent writes only its Star). `ANONYMOUS_AGENT` gets the
+ * Planet alone. `write` must name the same principal as `read`.
+ *
+ * Before CON-62 the Planet side was restricted to memories the principal's
+ * own agent wrote. Every local memory so far was written as `claude-code`,
+ * so a local store sees exactly what it saw; nothing is rewritten.
  */
 export declare function localGrant(read: ScopeFilter, opts?: {
     write?: ScopeFilter;
+    home?: Home;
+}): Grant;
+/**
+ * Every project of `p` (and its global memories), for read and write:
+ * maintenance such as export. Covers the same nodes as `localGrant`: the
+ * person's Planet and this agent's own Star.
+ */
+export declare function principalGrant(p: Principal, opts?: {
+    home?: Home;
 }): Grant;
-/** Every project of `p` (and its global memories), for read and write: maintenance such as export. */
-export declare function principalGrant(p: Principal): Grant;
 /**
  * A grant over explicit node patterns, possibly across owners and levels:
  * `read` bounds what is seen, `write` (default: `read`) what may change.
@@ -88,7 +123,19 @@ export declare function nodeGrant(opts: {
     principal: Principal;
     read: readonly NodePattern[];
     write?: readonly NodePattern[];
+    /** Where new memories land (default: the principal's Planet if written, else the first node written). */
+    home?: NodeRef;
 }): Grant;
+/**
+ * `g` narrowed to the nodes `keep` names (by `nodeKey`), on both sides: the
+ * grant recall uses for one node's first stage. Never wider than `g`. The
+ * home stays when it is kept, else the default for what remains.
+ */
+export declare function narrowGrant(g: Grant, keep: readonly NodeRef[]): Grant;
+/** The distinct nodes `g` reads, in the order its patterns name them. */
+export declare function readableNodes(g: Grant): NodeRef[];
+/** The address a new memory gets under `g`: its home node, bound to `projectId` when given. */
+export declare function homeAddress(g: Grant, projectId?: string): Address;
 /** Rejects anything that is not a real `Grant`; every store calls it first. */
 export declare function assertGrant(g: unknown): asserts g is Grant;
 /**