@psiclawops/hypermem 0.9.0 → 0.9.1

package/dist/doc-chunker.js

@@ -1,324 +0,0 @@
-/**
- * hypermem Document Chunker
- *
- * Splits markdown documents into semantically coherent chunks for L3 indexing.
- *
- * Design principles:
- * - Chunk by logical section (## / ###), NOT by token count
- * - Each chunk is a self-contained policy/operational unit
- * - Preserve section hierarchy for context assembly
- * - Track source file hash for atomic re-indexing
- * - Idempotent: same source produces same chunks (deterministic IDs)
- *
- * Collections (as defined in ACA offload spec):
- *   governance/policy   — POLICY.md, shared-fleet
- *   governance/charter  — CHARTER.md, per-tier (council/director)
- *   governance/comms    — COMMS.md, shared-fleet
- *   operations/agents   — AGENTS.md, per-tier
- *   operations/tools    — TOOLS.md, per-agent
- *   memory/decisions    — MEMORY.md, per-agent
- *   memory/daily        — memory/YYYY-MM-DD.md, per-agent
- *   identity/soul       — SOUL.md, per-agent (always-loaded kernel, but still indexed)
- *   identity/job        — JOB.md, per-agent (demand-loaded during deliberation)
- */
-import { createHash } from 'node:crypto';
-import { readFileSync } from 'node:fs';
-// ─── Core chunker ───────────────────────────────────────────────
-/**
- * Hash a string with SHA-256.
- */
-export function hashContent(content) {
-    return createHash('sha256').update(content).digest('hex');
-}
-/**
- * Estimate token count from character length.
- * Rough heuristic: 1 token ≈ 4 chars for English prose.
- */
-function estimateTokens(text) {
-    return Math.ceil(text.length / 4);
-}
-function parseMarkdownSections(markdown) {
-    const lines = markdown.split('\n');
-    const sections = [];
-    let currentLevel = 0;
-    let currentHeading = '';
-    let currentRaw = '';
-    let contentLines = [];
-    function flush() {
-        if (currentHeading || contentLines.length > 0) {
-            sections.push({
-                heading: currentHeading,
-                level: currentLevel,
-                content: contentLines.join('\n').trim(),
-                rawHeading: currentRaw,
-            });
-        }
-    }
-    for (const line of lines) {
-        const h3Match = line.match(/^### (.+)$/);
-        const h2Match = line.match(/^## (.+)$/);
-        const h1Match = line.match(/^# (.+)$/);
-        if (h3Match || h2Match || h1Match) {
-            flush();
-            currentRaw = line;
-            if (h3Match) {
-                currentLevel = 3;
-                currentHeading = h3Match[1].trim();
-            }
-            else if (h2Match) {
-                currentLevel = 2;
-                currentHeading = h2Match[1].trim();
-            }
-            else if (h1Match) {
-                currentLevel = 1;
-                currentHeading = h1Match[1].trim();
-            }
-            contentLines = [];
-        }
-        else {
-            contentLines.push(line);
-        }
-    }
-    flush();
-    return sections;
-}
-/**
- * Build a hierarchical section path from the section stack.
- * e.g., ["POLICY.md", "§3 Escalation", "Triggers"] → "POLICY.md > §3 Escalation > Triggers"
- */
-function buildSectionPath(stack) {
-    return stack.filter(Boolean).join(' > ');
-}
-/**
- * Generate a deterministic chunk ID from its identifying properties.
- * Includes sourcePath to prevent collisions when different files have
- * identical content and section structure (e.g., POLICY.md in two workspaces).
- */
-function chunkId(collection, sectionPath, sourceHash, sourcePath) {
-    const key = `${collection}::${sourcePath}::${sectionPath}::${sourceHash}`;
-    return createHash('sha256').update(key).digest('hex').slice(0, 16);
-}
-/**
- * Chunk a markdown document into semantic sections.
- *
- * Approach:
- * - Level 1 (#) headings become top-level section anchors
- * - Level 2 (##) headings become primary chunks
- * - Level 3 (###) headings become sub-chunks under their parent
- * - Content before the first heading becomes a "preamble" chunk
- * - Empty sections (heading only, no content) are skipped unless minContentLen=0
- *
- * For documents with deeply nested content, we group level-3 sections under
- * their parent level-2 section. This keeps related policy sections together.
- */
-export function chunkMarkdown(content, opts) {
-    const minLen = opts.minContentLen ?? 50;
-    const sourceHash = hashContent(content);
-    const sections = parseMarkdownSections(content);
-    const chunks = [];
-    // Track current section hierarchy for path building
-    let h1Heading = '';
-    let h2Heading = '';
-    const h2ContentLines = [];
-    let h2Active = false;
-    function flushH2() {
-        if (!h2Active)
-            return;
-        const body = h2ContentLines.join('\n').trim();
-        if (body.length < minLen && !opts.includeParentContext) {
-            h2Active = false;
-            h2ContentLines.length = 0;
-            return;
-        }
-        const sectionPath = buildSectionPath([h1Heading, h2Heading].filter(Boolean));
-        const chunkContent = [
-            h1Heading ? `# ${h1Heading}` : '',
-            `## ${h2Heading}`,
-            '',
-            body,
-        ].filter(l => l !== '' || body).join('\n').trim();
-        if (chunkContent.length >= minLen) {
-            chunks.push({
-                id: chunkId(opts.collection, sectionPath, sourceHash, opts.sourcePath),
-                collection: opts.collection,
-                sectionPath,
-                depth: 2,
-                content: chunkContent,
-                tokenEstimate: estimateTokens(chunkContent),
-                sourceHash,
-                sourcePath: opts.sourcePath,
-                scope: opts.scope,
-                tier: opts.tier,
-                agentId: opts.agentId,
-                parentPath: h1Heading || undefined,
-            });
-        }
-        h2Active = false;
-        h2ContentLines.length = 0;
-    }
-    // Preamble: text before first heading
-    let preamble = '';
-    for (const section of sections) {
-        if (section.level === 1) {
-            flushH2();
-            h1Heading = section.heading;
-            h2Heading = '';
-            // Level-1 headings with body content become a preamble chunk
-            if (section.content.length >= minLen) {
-                const sectionPath = buildSectionPath([h1Heading]);
-                const chunkContent = [`# ${h1Heading}`, '', section.content].join('\n').trim();
-                chunks.push({
-                    id: chunkId(opts.collection, sectionPath + '::intro', sourceHash, opts.sourcePath),
-                    collection: opts.collection,
-                    sectionPath: sectionPath + ' (intro)',
-                    depth: 1,
-                    content: chunkContent,
-                    tokenEstimate: estimateTokens(chunkContent),
-                    sourceHash,
-                    sourcePath: opts.sourcePath,
-                    scope: opts.scope,
-                    tier: opts.tier,
-                    agentId: opts.agentId,
-                });
-            }
-        }
-        else if (section.level === 2) {
-            flushH2();
-            h2Heading = section.heading;
-            h2Active = true;
-            // Start accumulating: begin with this section's own content
-            h2ContentLines.length = 0;
-            if (section.content)
-                h2ContentLines.push(section.content);
-        }
-        else if (section.level === 3) {
-            // Append h3 sub-sections into the current h2 chunk
-            if (h2Active) {
-                h2ContentLines.push(`\n### ${section.heading}`);
-                if (section.content)
-                    h2ContentLines.push(section.content);
-            }
-            else {
-                // h3 without a parent h2 — emit as standalone
-                const sectionPath = buildSectionPath([h1Heading, section.heading].filter(Boolean));
-                const chunkContent = [
-                    h1Heading ? `# ${h1Heading}` : '',
-                    `### ${section.heading}`,
-                    '',
-                    section.content,
-                ].filter(l => l !== '' || section.content).join('\n').trim();
-                if (chunkContent.length >= minLen) {
-                    chunks.push({
-                        id: chunkId(opts.collection, sectionPath, sourceHash, opts.sourcePath),
-                        collection: opts.collection,
-                        sectionPath,
-                        depth: 3,
-                        content: chunkContent,
-                        tokenEstimate: estimateTokens(chunkContent),
-                        sourceHash,
-                        sourcePath: opts.sourcePath,
-                        scope: opts.scope,
-                        tier: opts.tier,
-                        agentId: opts.agentId,
-                        parentPath: h1Heading || undefined,
-                    });
-                }
-            }
-        }
-        else if (section.level === 0) {
-            // Pre-heading content
-            preamble = section.content.trim();
-        }
-    }
-    // Flush any remaining h2
-    flushH2();
-    // Emit preamble if substantial
-    if (preamble.length >= minLen) {
-        chunks.unshift({
-            id: chunkId(opts.collection, '(preamble)', sourceHash, opts.sourcePath),
-            collection: opts.collection,
-            sectionPath: '(preamble)',
-            depth: 0,
-            content: preamble,
-            tokenEstimate: estimateTokens(preamble),
-            sourceHash,
-            sourcePath: opts.sourcePath,
-            scope: opts.scope,
-            tier: opts.tier,
-            agentId: opts.agentId,
-        });
-    }
-    return chunks;
-}
-/**
- * Chunk a file from disk.
- */
-export function chunkFile(filePath, opts) {
-    const content = readFileSync(filePath, 'utf-8');
-    return chunkMarkdown(content, { ...opts, sourcePath: filePath });
-}
-export const ACA_COLLECTIONS = {
-    'POLICY.md': {
-        collection: 'governance/policy',
-        scope: 'shared-fleet',
-        description: 'Governance policy: escalation triggers, decision states, council procedures, naming rules',
-    },
-    'CHARTER.md': {
-        collection: 'governance/charter',
-        scope: 'per-tier',
-        description: 'Org charter: mission, director structure, boundaries, escalation, work queue',
-    },
-    'COMMS.md': {
-        collection: 'governance/comms',
-        scope: 'shared-fleet',
-        description: 'Communications protocol: inter-agent tiers, delegation, platform formatting',
-    },
-    'AGENTS.md': {
-        collection: 'operations/agents',
-        scope: 'per-tier',
-        description: 'Agent operational guide: boot sequence, identity, memory, messaging, group chats',
-    },
-    'TOOLS.md': {
-        collection: 'operations/tools',
-        scope: 'per-agent',
-        description: 'Tool and runtime configuration: workspace path, model, key paths, quick commands',
-    },
-    'SOUL.md': {
-        collection: 'identity/soul',
-        scope: 'per-agent',
-        description: 'Agent soul: core principles, personality, tone, continuity',
-    },
-    'JOB.md': {
-        collection: 'identity/job',
-        scope: 'per-agent',
-        description: 'Job performance criteria: duties, response contract, council mode, output discipline',
-    },
-    'MOTIVATIONS.md': {
-        collection: 'identity/motivations',
-        scope: 'per-agent',
-        description: 'Agent motivations: drives, fears, tensions that shape perspective',
-    },
-    'MEMORY.md': {
-        collection: 'memory/decisions',
-        scope: 'per-agent',
-        description: 'Long-term curated memory: key decisions, lessons, context',
-    },
-};
-/**
- * Infer the collection definition for a file based on its name.
- * Returns undefined if the file is not a known ACA file.
- */
-export function inferCollection(fileName, agentId) {
-    // Strip path, get just the filename
-    const base = fileName.split('/').pop() ?? fileName;
-    // Daily memory files: memory/YYYY-MM-DD.md
-    if (/^\d{4}-\d{2}-\d{2}\.md$/.test(base)) {
-        return {
-            collection: 'memory/daily',
-            scope: 'per-agent',
-            description: `Daily memory log for ${agentId || 'agent'}`,
-        };
-    }
-    return ACA_COLLECTIONS[base];
-}
-//# sourceMappingURL=doc-chunker.js.map

package/dist/dreaming-promoter.d.ts

@@ -1,124 +0,0 @@
-/**
- * dreaming-promoter.ts
- *
- * hypermem-native dreaming promotion pass.
- *
- * Unlike the stock memory-core dreaming feature (which appends raw content to
- * MEMORY.md), this promoter generates pointer-format entries that match the
- * council's MEMORY.md convention:
- *
- *   - **{domain} — {title}:** {summary}
- *     → `memory_search("{query}")`
- *
- * Scoring uses confidence, decay, recency, and domain cluster weight.
- * Dedup prevents re-promoting topics already covered by existing pointers.
- *
- * Dry-run mode returns what would be written without modifying any files.
- */
-import type { DatabaseSync } from 'node:sqlite';
-export interface DreamerConfig {
-    /** Enable the promotion pass. Default: false */
-    enabled: boolean;
-    /** Minimum composite score for promotion. Default: 0.70 */
-    minScore: number;
-    /** Minimum confidence threshold (pre-scoring). Default: 0.70 */
-    minConfidence: number;
-    /** Max new pointer entries to write per agent per run. Default: 5 */
-    maxPromotionsPerRun: number;
-    /** How often to run: every N indexer ticks. Default: 12 (~1hr at 5min interval) */
-    tickInterval: number;
-    /** Preview what would be promoted without writing. Default: false */
-    dryRun: boolean;
-    /** Recency half-life in days (score decays to 0.5 at this age). Default: 14 */
-    recencyHalfLifeDays: number;
-    /** Max age in days to consider a fact. Default: 90 */
-    maxAgeDays: number;
-}
-export declare const DEFAULT_DREAMER_CONFIG: DreamerConfig;
-export interface FactCandidate {
-    id: number;
-    agentId: string;
-    domain: string;
-    content: string;
-    confidence: number;
-    decayScore: number;
-    ageDays: number;
-    score: number;
-}
-export interface PromotionEntry {
-    factId: number;
-    domain: string;
-    pointer: string;
-    title: string;
-    summary: string;
-    query: string;
-    score: number;
-    dryRun: boolean;
-}
-export interface DreamerResult {
-    agentId: string;
-    candidates: number;
-    promoted: number;
-    skippedDuplicate: number;
-    skippedThreshold: number;
-    entries: PromotionEntry[];
-    memoryPath: string | null;
-    dryRun: boolean;
-}
-/**
- * Resolve the workspace directory for an agent.
- * Council agents live at ~/.openclaw/workspace/{agentId}/
- * Other agents at ~/.openclaw/workspace/{agentId}/
- */
-export declare function resolveAgentWorkspacePath(agentId: string): Promise<string | null>;
-/**
- * Temporal-state markers that indicate a fact is time-bound or conditional.
- *
- * Facts containing any of these markers MUST carry structured recency metadata
- * (`validFrom` / `invalidAt` columns) to be eligible for durable promotion.
- * Plain ISO dates in the content text do NOT satisfy this requirement — a
- * dated sentence like "suspended pending X as of 2026-04-18" is still temporary
- * and would harden stale state if promoted.
- *
- * Exported so tests and downstream callers can verify coverage and extend it.
- * Keep this list centralized; do not fork copies into other modules.
- */
-export declare const TEMPORAL_MARKERS: RegExp[];
-/**
- * Returns true if content contains any temporal-state marker.
- * Exported for test coverage and for callers that want to gate their own writes.
- */
-export declare function hasTemporalMarker(content: string): boolean;
-/**
- * Structured recency metadata from the facts table.
- * Either field being set (non-null, non-empty) signals the fact row was
- * authored with temporal bounds the store can enforce.
- */
-export interface FactRecencyMeta {
-    validFrom?: string | null;
-    invalidAt?: string | null;
-}
-/**
- * Reject facts that are clearly noise at promotion time.
- * A second line of defense — the indexer's isQualityFact() is the primary filter,
- * but legacy noise in the DB (pre-TUNE-013) still needs to be caught here.
- *
- * Additionally blocks promotion of temporally-scoped facts that lack structured
- * recency metadata. A fact like "model frozen until provider routing stable"
- * without `validFrom`/`invalidAt` would harden a temporary state into durable
- * memory forever. Plain ISO dates in content text do NOT bypass this check.
- */
-export declare function isPromotable(content: string, meta?: FactRecencyMeta): boolean;
-/**
- * Run the dreaming promotion pass for a single agent.
- *
- * Reads qualified facts from library.db, scores them, deduplicates against
- * existing MEMORY.md pointers, and writes new pointer entries.
- */
-export declare function runDreamingPromoter(agentId: string, libraryDb: DatabaseSync, config?: Partial<DreamerConfig>): Promise<DreamerResult>;
-/**
- * Run the dreaming promotion pass for all agents in a fleet.
- * Called from the BackgroundIndexer on every N ticks.
- */
-export declare function runDreamingPassForFleet(agentIds: string[], libraryDb: DatabaseSync, config?: Partial<DreamerConfig>): Promise<DreamerResult[]>;
-//# sourceMappingURL=dreaming-promoter.d.ts.map

package/dist/dreaming-promoter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"dreaming-promoter.d.ts","sourceRoot":"","sources":["../src/dreaming-promoter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mFAAmF;IACnF,YAAY,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,+EAA+E;IAC/E,mBAAmB,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,sBAAsB,EAAE,aASpC,CAAC;AAIF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,OAAO,CAAC;CACjB;AAID;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgBvF;AAoKD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,EAyBpC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AASD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAsD7E;AAGD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,YAAY,EACvB,MAAM,GAAE,OAAO,CAAC,aAAa,CAAM,GAClC,OAAO,CAAC,aAAa,CAAC,CAoJxB;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAAE,EAClB,SAAS,EAAE,YAAY,EACvB,MAAM,GAAE,OAAO,CAAC,aAAa,CAAM,GAClC,OAAO,CAAC,aAAa,EAAE,CAAC,CAa1B"}