@remnic/core 1.0.0

package/dist/temporal-index.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Temporal and Tag Indexes (v8.1 — SwiftMem-inspired)
+ *
+ * Maintains two fast on-disk lookup structures in `state/`:
+ *   index_time.json — maps YYYY-MM-DD date buckets to memory file paths
+ *   index_tags.json — maps tag strings to memory file paths
+ *
+ * Used as an optional prefilter in the retrieval pipeline:
+ * given a time range or a set of tags, narrow the candidate set
+ * before the QMD hybrid search so we can pass a smaller pool to scoring.
+ *
+ * Design constraints:
+ * - Must be fail-open (any error returns empty / unfiltered)
+ * - Reads/writes are batched per extraction run
+ * - Both indexes are plain JSON; no external dependencies
+ */
+interface TemporalIndex {
+    /** version bumped when schema changes */
+    version: number;
+    /** Last full rebuild timestamp (ISO string) */
+    lastRebuildAt?: string;
+    /** Map from YYYY-MM-DD → array of memory paths */
+    dates: Record<string, string[]>;
+}
+interface TagIndex {
+    version: number;
+    lastRebuildAt?: string;
+    /** Map from canonical tag string → node metadata */
+    tags: Record<string, TagNode | string[]>;
+    /** Map from alias string → canonical tags */
+    aliases?: Record<string, string[]>;
+}
+interface TagNode {
+    paths: string[];
+    aliases?: string[];
+    parents?: string[];
+}
+/**
+ * Add (or update) a memory file in both indexes.
+ *
+ * @param memoryDir Root memory directory
+ * @param memoryPath Absolute path to the memory file
+ * @param createdAt ISO timestamp of the memory's creation date
+ * @param tags Array of tag strings from the memory's frontmatter
+ */
+declare function indexMemory(memoryDir: string, memoryPath: string, createdAt: string, tags: string[]): void;
+/**
+ * Remove a memory file from both indexes (called on deletion/archival).
+ */
+declare function deindexMemory(memoryDir: string, memoryPath: string, createdAt: string, tags: string[]): void;
+/**
+ * Reset both index files to empty state.
+ * Called before a full-corpus rebuild so stale paths in any surviving index
+ * file do not persist after the rebuild completes.
+ */
+declare function clearIndexes(memoryDir: string): void;
+/**
+ * Returns true when both index files exist on disk.
+ * Used to detect first-time enablement so callers can trigger a full rebuild.
+ */
+declare function indexesExist(memoryDir: string): boolean;
+/**
+ * Batch-add multiple memories to both indexes in a single read-modify-write cycle.
+ * More efficient than calling indexMemory() per file when adding many at once.
+ */
+declare function indexMemoriesBatch(memoryDir: string, entries: Array<{
+    path: string;
+    createdAt: string;
+    tags: string[];
+}>): void;
+/**
+ * Return the set of memory paths whose index date falls in [fromDate, toDate).
+ *
+ * Boundary semantics (exclusive upper bound):
+ * - `fromDate` is INCLUSIVE — entries on this date ARE returned.
+ * - `toDate`   is EXCLUSIVE — entries on this date are NOT returned.
+ *   Pass `recencyWindowBoundsFromPrompt(query).toDate` to get the correct
+ *   exclusive boundary; do NOT add +1 day yourself.
+ * - Default `toDate` = tomorrow, so omitting it includes all of today.
+ *
+ * @param memoryDir - root memory directory (contains state/index_time.json)
+ * @param fromDate  - inclusive start date, YYYY-MM-DD
+ * @param toDate    - exclusive end date, YYYY-MM-DD (default: tomorrow)
+ * @returns Set of matching file paths, or null if the index is unavailable.
+ */
+declare function queryByDateRangeAsync(memoryDir: string, fromDate: string, toDate?: string): Promise<Set<string> | null>;
+/**
+ * Async version of queryByTags — uses non-blocking fs.promises.readFile
+ * to avoid blocking the Node.js event loop.
+ */
+declare function queryByTagsAsync(memoryDir: string, tags: string[]): Promise<Set<string> | null>;
+/**
+ * Extract tags from a prompt for tag-based prefiltering.
+ * Looks for hashtag-style tokens (#foo).
+ * Returns lowercase, deduplicated list.
+ */
+declare function extractTagsFromPrompt(prompt: string): string[];
+declare function resolvePromptTagPrefilterAsync(memoryDir: string, prompt: string): Promise<{
+    matchedTags: string[];
+    expandedTags: string[];
+    paths: Set<string> | null;
+}>;
+/**
+ * Detect if a prompt is time-sensitive (mentions specific time references).
+ * Used to decide whether to activate the temporal prefilter.
+ */
+declare function isTemporalQuery(prompt: string): boolean;
+/**
+ * Compute a "from date" string (YYYY-MM-DD) for a recency-based temporal query.
+ * For "recent" / "lately" returns 7 days ago; for today/yesterday the obvious window.
+ */
+declare function recencyWindowFromPrompt(prompt: string, nowMs?: number): string;
+/**
+ * Returns both the start and end of the temporal window implied by the prompt.
+ *
+ * `fromDate` is computed by delegating to `recencyWindowFromPrompt`, so the two
+ * functions cannot diverge on the lower bound.  `toDate` is computed independently
+ * here using the same pattern-priority ordering, because the upper-bound arithmetic
+ * differs (exclusive end vs. inclusive start) and would not be expressible as a
+ * simple wrapper.
+ *
+ * Known divergence to be aware of: for "N hours ago", `recencyWindowFromPrompt`
+ * uses `Math.max(1, Math.ceil(hours/24))` days back, so `fromDate` = yesterday for
+ * sub-24h values.  `toDate` here is always `tomorrow` when no explicit date is
+ * specified (see the `toDaysBack === 0` branch), giving a 2-day window.  This is
+ * intentional — the window must cover both yesterday and today for recent hour-level
+ * queries.  Any fix to the hours formula in `recencyWindowFromPrompt` must be
+ * manually reflected here.
+ *
+ * - `fromDate`: first day of the implied window (same as `recencyWindowFromPrompt`)
+ * - `toDate`: first day NOT in the window (exclusive upper bound), so callers
+ *   should filter with `date >= fromDate && date < toDate`.
+ */
+declare function recencyWindowBoundsFromPrompt(prompt: string, nowMs?: number): {
+    fromDate: string;
+    toDate: string;
+};
+
+export { type TagIndex, type TagNode, type TemporalIndex, clearIndexes, deindexMemory, extractTagsFromPrompt, indexMemoriesBatch, indexMemory, indexesExist, isTemporalQuery, queryByDateRangeAsync, queryByTagsAsync, recencyWindowBoundsFromPrompt, recencyWindowFromPrompt, resolvePromptTagPrefilterAsync };

package/dist/temporal-index.js

@@ -0,0 +1,29 @@
+import {
+  clearIndexes,
+  deindexMemory,
+  extractTagsFromPrompt,
+  indexMemoriesBatch,
+  indexMemory,
+  indexesExist,
+  isTemporalQuery,
+  queryByDateRangeAsync,
+  queryByTagsAsync,
+  recencyWindowBoundsFromPrompt,
+  recencyWindowFromPrompt,
+  resolvePromptTagPrefilterAsync
+} from "./chunk-V3RXWQIE.js";
+export {
+  clearIndexes,
+  deindexMemory,
+  extractTagsFromPrompt,
+  indexMemoriesBatch,
+  indexMemory,
+  indexesExist,
+  isTemporalQuery,
+  queryByDateRangeAsync,
+  queryByTagsAsync,
+  recencyWindowBoundsFromPrompt,
+  recencyWindowFromPrompt,
+  resolvePromptTagPrefilterAsync
+};
+//# sourceMappingURL=temporal-index.js.map

package/dist/temporal-index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/threading.d.ts

@@ -0,0 +1,62 @@
+import { BufferTurn, ConversationThread } from './types.js';
+
+/**
+ * Conversation Threading (Phase 3B)
+ *
+ * Groups related memories into conversation threads with auto-generated titles.
+ * Thread boundary detection: new session key OR time gap > threshold.
+ */
+
+declare class ThreadingManager {
+    private readonly threadsDir;
+    private readonly gapMinutes;
+    private currentThreadId;
+    private lastTurnTimestamp;
+    private lastSessionKey;
+    constructor(threadsDir: string, gapMinutes?: number);
+    ensureDirectory(): Promise<void>;
+    /**
+     * Check if we should start a new thread based on session key and time gap.
+     */
+    shouldStartNewThread(turn: BufferTurn): boolean;
+    /**
+     * Process a turn and return the thread ID it belongs to.
+     * Creates a new thread if needed.
+     */
+    processTurn(turn: BufferTurn, episodeIds: string[]): Promise<string>;
+    /**
+     * Append persisted memory IDs to an existing thread.
+     * Keeps IDs unique and updates the thread timestamp.
+     */
+    appendEpisodeIds(threadId: string, episodeIds: string[]): Promise<void>;
+    /**
+     * Update thread title based on accumulated content.
+     */
+    updateThreadTitle(threadId: string, content: string): Promise<void>;
+    /**
+     * Get all threads, sorted by updatedAt desc.
+     */
+    getAllThreads(): Promise<ConversationThread[]>;
+    /**
+     * Get a thread by ID.
+     */
+    loadThread(threadId: string): Promise<ConversationThread | null>;
+    /**
+     * Save a thread.
+     */
+    saveThread(thread: ConversationThread): Promise<void>;
+    /**
+     * Link two threads together.
+     */
+    linkThreads(threadId1: string, threadId2: string): Promise<boolean>;
+    /**
+     * Get the current thread ID (if any).
+     */
+    getCurrentThreadId(): string | null;
+    /**
+     * Reset threading state (e.g., on plugin restart).
+     */
+    reset(): void;
+}
+
+export { ThreadingManager };

package/dist/threading.js

@@ -0,0 +1,8 @@
+import {
+  ThreadingManager
+} from "./chunk-UCYSTFZR.js";
+import "./chunk-KWBU5S5U.js";
+export {
+  ThreadingManager
+};
+//# sourceMappingURL=threading.js.map

package/dist/threading.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/tier-migration.d.ts

@@ -0,0 +1,44 @@
+import { MemoryFile } from './types.js';
+import { StorageManager } from './storage.js';
+import { MemoryTier } from './tier-routing.js';
+import { S as SearchBackend } from './port-C1GZFv8h.js';
+import './memory-projection-store-NxMkbocT.js';
+import 'better-sqlite3';
+import './lifecycle.js';
+
+interface TierMigrationRequest {
+    memory: MemoryFile;
+    fromTier: MemoryTier;
+    toTier: MemoryTier;
+    reason: string;
+}
+interface TierMigrationResult {
+    memoryId: string;
+    fromTier: MemoryTier;
+    toTier: MemoryTier;
+    changed: boolean;
+    reason: string;
+    targetPath: string;
+}
+interface TierMigrationExecutorOptions {
+    storage: StorageManager;
+    qmd: SearchBackend;
+    hotCollection: string;
+    coldCollection: string;
+    autoEmbed?: boolean;
+    journalPath?: string;
+}
+declare class TierMigrationExecutor {
+    private readonly storage;
+    private readonly qmd;
+    private readonly hotCollection;
+    private readonly coldCollection;
+    private readonly autoEmbed;
+    private readonly journalPath;
+    constructor(options: TierMigrationExecutorOptions);
+    migrateMemory(request: TierMigrationRequest): Promise<TierMigrationResult>;
+    private collectionForTier;
+    private appendJournal;
+}
+
+export { MemoryTier, TierMigrationExecutor, type TierMigrationExecutorOptions, type TierMigrationRequest, type TierMigrationResult };

package/dist/tier-migration.js

@@ -0,0 +1,7 @@
+import {
+  TierMigrationExecutor
+} from "./chunk-Z5AAYHUC.js";
+export {
+  TierMigrationExecutor
+};
+//# sourceMappingURL=tier-migration.js.map

package/dist/tier-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/tier-routing.d.ts

@@ -0,0 +1,21 @@
+import { MemoryFile } from './types.js';
+import { LifecycleSignals } from './lifecycle.js';
+
+type MemoryTier = "hot" | "cold";
+interface TierRoutingPolicy {
+    enabled: boolean;
+    demotionMinAgeDays: number;
+    demotionValueThreshold: number;
+    promotionValueThreshold: number;
+}
+interface TierTransitionDecision {
+    currentTier: MemoryTier;
+    nextTier: MemoryTier;
+    valueScore: number;
+    changed: boolean;
+    reason: string;
+}
+declare function computeTierValueScore(memory: Pick<MemoryFile, "frontmatter">, now: Date, signals?: LifecycleSignals): number;
+declare function decideTierTransition(memory: Pick<MemoryFile, "frontmatter">, currentTier: MemoryTier, policy: TierRoutingPolicy, now: Date, signals?: LifecycleSignals): TierTransitionDecision;
+
+export { type MemoryTier, type TierRoutingPolicy, type TierTransitionDecision, computeTierValueScore, decideTierTransition };

package/dist/tier-routing.js

@@ -0,0 +1,10 @@
+import {
+  computeTierValueScore,
+  decideTierTransition
+} from "./chunk-4A24LIM2.js";
+import "./chunk-QCCCQT3O.js";
+export {
+  computeTierValueScore,
+  decideTierTransition
+};
+//# sourceMappingURL=tier-routing.js.map

package/dist/tier-routing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/tmt.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Temporal Memory Tree (TiMem-inspired, v8.2)
+ *
+ * Builds a hierarchy of summarised memory nodes:
+ *   hour-HH.md → day.md → week-YYYY-WW.md → persona.md
+ *
+ * Stored under `<baseDir>/tmt/`.
+ * All writes are fail-open: errors are caught and logged, never thrown.
+ */
+declare const TMT_DIR = "tmt";
+type TmtLevel = "hour" | "day" | "week" | "persona";
+interface TmtNodeFrontmatter {
+    level: TmtLevel;
+    periodStart: string;
+    periodEnd: string;
+    memoryCount: number;
+    sourceIds: string[];
+    builtAt: string;
+}
+interface TmtConfig {
+    temporalMemoryTreeEnabled: boolean;
+    tmtHourlyMinMemories: number;
+    tmtSummaryMaxTokens: number;
+}
+interface MemoryEntry {
+    path: string;
+    id: string;
+    created: string;
+    content: string;
+}
+declare function capTmtSummaryInputs(inputs: string[], level: TmtLevel): string[];
+declare function tmtDir(baseDir: string): string;
+declare function hourNodePath(baseDir: string, date: string, hour: string): string;
+declare function dayNodePath(baseDir: string, date: string): string;
+declare function weekNodePath(baseDir: string, weekKey: string): string;
+declare function personaNodePath(baseDir: string): string;
+declare function serialiseTmtNode(fm: TmtNodeFrontmatter, summary: string): string;
+declare function parseIsoDate(iso: string): string;
+declare function parseIsoHour(iso: string): string;
+declare function isoWeekKey(date: Date): string;
+type SummarizeFn = (memories: string[], level: TmtLevel) => Promise<string>;
+declare class TmtBuilder {
+    private readonly baseDir;
+    private readonly cfg;
+    constructor(baseDir: string, cfg: TmtConfig);
+    /**
+     * Called after each consolidation pass.
+     * Groups memories by hour, builds any missing hour nodes,
+     * then rolls up to day → week → persona if needed.
+     * All errors are caught and logged; never throws.
+     */
+    maybeRebuildNodes(memories: MemoryEntry[], summarize: SummarizeFn): Promise<void>;
+    private buildHourNodes;
+    private buildDayNodes;
+    /**
+     * Build or update week-level nodes from the day nodes already on disk.
+     * Groups memories by ISO week; for each week that has a day node but no
+     * (or stale) week node, reads day node summaries and builds a week node.
+     * Fail-open: errors per week are caught and skipped.
+     */
+    private buildWeekNodes;
+    /**
+     * Build or update the persona node from the most recent week-level summaries.
+     * Reads up to 4 recent week nodes and synthesizes a persona-level narrative.
+     * Fail-open: skips silently if no week nodes exist or summarize fails.
+     */
+    private buildPersonaNode;
+    /**
+     * Return the summary text of the most relevant TMT node for a given prompt.
+     * Preference: day node for today > most recent day node.
+     * Returns null if no nodes exist or feature is disabled.
+     */
+    getMostRelevantNode(): Promise<{
+        level: TmtLevel;
+        summary: string;
+    } | null>;
+}
+
+export { type MemoryEntry, type SummarizeFn, TMT_DIR, TmtBuilder, type TmtConfig, type TmtLevel, type TmtNodeFrontmatter, capTmtSummaryInputs, dayNodePath, hourNodePath, isoWeekKey, parseIsoDate, parseIsoHour, personaNodePath, serialiseTmtNode, tmtDir, weekNodePath };

package/dist/tmt.js

@@ -0,0 +1,29 @@
+import {
+  TMT_DIR,
+  TmtBuilder,
+  capTmtSummaryInputs,
+  dayNodePath,
+  hourNodePath,
+  isoWeekKey,
+  parseIsoDate,
+  parseIsoHour,
+  personaNodePath,
+  serialiseTmtNode,
+  tmtDir,
+  weekNodePath
+} from "./chunk-TPB3I2AC.js";
+export {
+  TMT_DIR,
+  TmtBuilder,
+  capTmtSummaryInputs,
+  dayNodePath,
+  hourNodePath,
+  isoWeekKey,
+  parseIsoDate,
+  parseIsoHour,
+  personaNodePath,
+  serialiseTmtNode,
+  tmtDir,
+  weekNodePath
+};
+//# sourceMappingURL=tmt.js.map

package/dist/tmt.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/tokens.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Token management for Remnic multi-connector auth.
+ *
+ * Manages per-connector tokens in ~/.remnic/tokens.json.
+ * Each connector gets a unique token with a recognizable prefix.
+ */
+interface TokenEntry {
+    token: string;
+    connector: string;
+    createdAt: string;
+}
+interface TokenStore {
+    tokens: TokenEntry[];
+}
+declare function loadTokenStore(tokensPath?: string): TokenStore;
+declare function saveTokenStore(store: TokenStore, tokensPath?: string): void;
+declare function generateToken(connector: string, tokensPath?: string): TokenEntry;
+declare function listTokens(tokensPath?: string): TokenEntry[];
+declare function revokeToken(connector: string, tokensPath?: string): boolean;
+declare function getAllValidTokens(tokensPath?: string): string[];
+declare function getAllValidTokensCached(tokensPath?: string): string[];
+declare function resolveConnectorFromToken(token: string, tokensPath?: string): string | undefined;
+
+export { type TokenEntry, type TokenStore, generateToken, getAllValidTokens, getAllValidTokensCached, listTokens, loadTokenStore, resolveConnectorFromToken, revokeToken, saveTokenStore };

package/dist/tokens.js

@@ -0,0 +1,21 @@
+import {
+  generateToken,
+  getAllValidTokens,
+  getAllValidTokensCached,
+  listTokens,
+  loadTokenStore,
+  resolveConnectorFromToken,
+  revokeToken,
+  saveTokenStore
+} from "./chunk-KL4CP4SB.js";
+export {
+  generateToken,
+  getAllValidTokens,
+  getAllValidTokensCached,
+  listTokens,
+  loadTokenStore,
+  resolveConnectorFromToken,
+  revokeToken,
+  saveTokenStore
+};
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/topics.d.ts

@@ -0,0 +1,29 @@
+import { MemoryFile, TopicScore } from './types.js';
+
+/**
+ * Topic Extraction (Phase 4B)
+ *
+ * Extract key topics from all memories using TF-IDF weighting.
+ * Runs as a batch process during consolidation.
+ */
+
+/**
+ * Calculate TF-IDF scores for terms across all memories.
+ *
+ * TF (term frequency) = count of term in document / total terms in document
+ * IDF (inverse document frequency) = log(total documents / documents containing term)
+ * TF-IDF = TF * IDF
+ *
+ * Terms with high TF-IDF are frequent in specific memories but rare overall.
+ */
+declare function extractTopics(memories: MemoryFile[], topN?: number): TopicScore[];
+/**
+ * Compare two topic lists to find trending changes.
+ * Returns topics that are new or significantly increased.
+ */
+declare function findTrendingTopics(currentTopics: TopicScore[], previousTopics: TopicScore[], threshold?: number): {
+    rising: TopicScore[];
+    falling: TopicScore[];
+};
+
+export { extractTopics, findTrendingTopics };

package/dist/topics.js

@@ -0,0 +1,9 @@
+import {
+  extractTopics,
+  findTrendingTopics
+} from "./chunk-UHGBNIOS.js";
+export {
+  extractTopics,
+  findTrendingTopics
+};
+//# sourceMappingURL=topics.js.map

package/dist/topics.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}