rag-memory-epf-mcp 5.1.0 → 5.2.0

package/dist/index.d.ts

@@ -70,6 +70,7 @@ export declare class RAGKnowledgeGraphManager {
     currentProfileId: number;
     grandfatherAllowed: boolean;
     coordinator: BackfillCoordinator | null;
+    readonly calendarTimeZone: string;
     private embeddingCache;
     private readonly EMBEDDING_CACHE_MAX;
     private dictionaryCache;

package/dist/index.js

@@ -32,6 +32,7 @@ import { migrations } from './src/migrations/migrations.js';
 import { EmbeddingGate, GateNotReadyError, GateDisabledError, TerminalConfigError } from './src/embeddingGate.js';
 import { resolveModelCacheDir, preflightCacheDir, artifactKey, ModelDownloadLock, handleLoaderFailure } from './src/modelCache.js';
 import { BackfillCoordinator } from './src/backfillCoordinator.js';
+import { calendarDate, resolveCalendarTimeZone, stampDatePrefix, stripDatePrefix } from './src/observations/date-prefix.js';
 import os from 'node:os';
 import { createHash } from 'crypto';
 import { createRequire } from 'module';
@@ -179,6 +180,9 @@ export class RAGKnowledgeGraphManager {
     // default model config, or with the explicit trust opt-in (spec §6b guard).
     grandfatherAllowed = IS_DEFAULT_MODEL_CONFIG || process.env.RAG_MEMORY_TRUST_LEGACY_VECTORS === '1';
     coordinator = null;
+    // The calendar that date-only human labels are written in. Resolved once, here, so an invalid
+    // zone fails at construction instead of quietly writing wrong days for weeks.
+    calendarTimeZone = resolveCalendarTimeZone(process.env.RAG_MEMORY_CALENDAR_TZ);
     embeddingCache = new Map();
     EMBEDDING_CACHE_MAX = 500;
     dictionaryCache = null;
@@ -574,11 +578,12 @@ export class RAGKnowledgeGraphManager {
     }
     // === ORIGINAL MCP FUNCTIONALITY ===
     _timestampObservation(obs) {
-        // If observation already has a date prefix like [2026-03-21], skip
-        if (/^\[\d{4}-\d{2}-\d{2}\]/.test(obs))
-            return obs;
-        const today = new Date().toISOString().slice(0, 10);
-        return `[${today}] ${obs}`;
+        // Stamp and dedup share one parser (src/observations/date-prefix.ts). They used to carry
+        // separate regexes and disagreed about "[2026-08-11 session16] ...": stamping treated it as
+        // undated and prepended a second date, while dedup could not strip it — so the same sentence
+        // written in two sessions became two observations. Measured on a live database: 82 rows with
+        // two dates, 29 with a day earlier than the day they were written.
+        return stampDatePrefix(obs, this.calendarTimeZone);
     }
     async createEntities(entities) {
         if (!this.db)
@@ -590,7 +595,7 @@ export class RAGKnowledgeGraphManager {
       INSERT OR IGNORE INTO entities (id, name, entityType, observations, metadata)
       VALUES (?, ?, ?, '[]', ?)
     `);
-        const stripDate = (s2) => s2.replace(/^\[\d{4}-\d{2}-\d{2}\]\s*/, '');
+        const stripDate = stripDatePrefix; // shared with the stamp path — see date-prefix.ts
         for (const entity of entities) {
             const entityId = `entity_${entity.name.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`;
             const ts = new Date().toISOString();
@@ -700,7 +705,7 @@ export class RAGKnowledgeGraphManager {
             // dedup 기준은 v3.6 과 같다: 날짜 prefix 를 뗀 본문이 active 에 이미 있으면
             // 새 revision 을 만들지 않는다. 다만 v13 에서는 같은 사실이 다른 출처에서 다시
             // 온 것이므로 그 revision 에 source link 를 더한다(spec §8.3 T13).
-            const stripDate = (s2) => s2.replace(/^\[\d{4}-\d{2}-\d{2}\]\s*/, '');
+            const stripDate = stripDatePrefix; // shared with the stamp path — see date-prefix.ts
             const activeRows = this.db.prepare(`SELECT observation_id, content FROM entity_observations
          WHERE entity_id = ? AND status = 'active'`).all(entityId);
             const activeByBare = new Map(activeRows.map(r => [stripDate(r.content), r.observation_id]));
@@ -1963,7 +1968,10 @@ export class RAGKnowledgeGraphManager {
             // report `unchanged` for a different exclusion, which is the silent-wrong case.
             const content = applyExcludePatterns(options.content !== undefined ? options.content : fsSync.readFileSync(filePath, 'utf-8'), options.excludePattern);
             const bytes = Buffer.byteLength(content, 'utf-8');
-            const today = new Date().toISOString().slice(0, 10);
+            // Same calendar as the observation prefix. Deciding this explicitly rather than leaving it
+            // on UTC: both are date-only labels a person reads, and "observations in Seoul days but
+            // documents in UTC days" is not a distinction anyone could explain later.
+            const today = calendarDate(new Date(), this.calendarTimeZone);
             const contentHash = shaHex(content);
             // spec §5.1: content_hash 는 system-owned — user metadata 뒤에 쓴다 (r1: spread 가 덮어쓸 수 있었다).
             const metadata = { source: filePath, updated: today, ...(options.metadata || {}), content_hash: contentHash };
@@ -3452,6 +3460,9 @@ export class RAGKnowledgeGraphManager {
             server: {
                 version: PKG_VERSION,
                 node: process.versions.node,
+                // Which calendar produced the date-only labels in this database. Surfaced because a
+                // wrong value is otherwise invisible: the labels look plausible either way.
+                calendar_timezone: this.calendarTimeZone,
                 embeddings_mode: this.embeddingsMode,
                 model: `${EMBEDDING_MODEL}@${MODEL_REVISION}`,
                 model_state: gs.state,

package/dist/src/observations/date-prefix.d.ts

@@ -0,0 +1,26 @@
+/** The calendar day of `instant` in `timeZone`, as YYYY-MM-DD. */
+export declare function calendarDate(instant: Date, timeZone: string): string;
+/**
+ * Resolve RAG_MEMORY_CALENDAR_TZ. Unset or blank means UTC. An unrecognised zone throws at
+ * boot rather than silently falling back — a wrong-but-quiet calendar writes wrong labels for
+ * as long as nobody looks, which is the failure this whole module exists to end.
+ */
+export declare function resolveCalendarTimeZone(raw: string | undefined | null): string;
+export interface DatePrefix {
+    /** YYYY-MM-DD, already validated as a real calendar day. */
+    date: string;
+    /** Text between the date and the closing bracket, e.g. a session marker. */
+    annotation: string | null;
+    /** The matched prefix including the brackets, without trailing whitespace. */
+    matched: string;
+}
+/** Parse a leading date prefix, or null when the text does not start with one. */
+export declare function parseDatePrefix(content: string): DatePrefix | null;
+/**
+ * The dedup key: the text with its date prefix removed. The annotation comes off with the date
+ * because it records *when and in which session the line was written*, not what the line claims
+ * — the same sentence written in two sessions is one fact, and dedup has to see that.
+ */
+export declare function stripDatePrefix(content: string): string;
+/** Prepend today's calendar day unless the text already carries a valid date prefix. */
+export declare function stampDatePrefix(content: string, timeZone: string, now?: Date): string;

package/dist/src/observations/date-prefix.js

@@ -0,0 +1,89 @@
+// One place that decides what a leading "[date]" on an observation means.
+//
+// Why this is a module and not two regexes inline: the stamp path and the dedup path each had
+// their own copy of the pattern, and they disagreed. Stamping asked "does this already start
+// with a date?" while dedup asked "what is this text without its date?", so widening one without
+// the other let the same sentence be stored twice under two session markers. Both now call in
+// here.
+//
+// Why an explicit timezone instead of the process one: a date-only label has no meaning until
+// you say which calendar produced it. The same database is reached from a laptop, from CI and
+// from another country; deriving the day from the ambient TZ makes the stored string mean
+// something different on each. The default stays UTC so the product does not inherit whichever
+// zone its first author happened to sit in — a deployment that wants local days says so.
+/** The calendar day of `instant` in `timeZone`, as YYYY-MM-DD. */
+export function calendarDate(instant, timeZone) {
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).formatToParts(instant);
+    const part = (type) => {
+        const found = parts.find(p => p.type === type);
+        if (!found)
+            throw new Error(`calendarDate: missing ${type} for timeZone ${timeZone}`);
+        return found.value;
+    };
+    return `${part('year')}-${part('month')}-${part('day')}`;
+}
+/**
+ * Resolve RAG_MEMORY_CALENDAR_TZ. Unset or blank means UTC. An unrecognised zone throws at
+ * boot rather than silently falling back — a wrong-but-quiet calendar writes wrong labels for
+ * as long as nobody looks, which is the failure this whole module exists to end.
+ */
+export function resolveCalendarTimeZone(raw) {
+    const value = (raw ?? '').trim();
+    if (!value)
+        return 'UTC';
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: value });
+    }
+    catch {
+        throw new Error(`RAG_MEMORY_CALENDAR_TZ is not a recognised IANA time zone: ${JSON.stringify(value)}. ` +
+            `Use a name like "Asia/Seoul", or leave it unset for UTC.`);
+    }
+    return value;
+}
+// The annotation may not contain a newline or a bracket: an unclosed or multi-line "[2026-…"
+// is prose that happens to start with a digit, not a prefix. Requiring the closing bracket is
+// what keeps "[2026-08-11 unclosed" and "[2026-08-111]" out.
+const PREFIX_RE = /^\[(\d{4})-(\d{2})-(\d{2})(?:[ \t]([^\]\n]*))?\]/;
+function isRealCalendarDay(year, month, day) {
+    const asUtc = new Date(Date.UTC(year, month - 1, day));
+    return asUtc.getUTCFullYear() === year
+        && asUtc.getUTCMonth() === month - 1
+        && asUtc.getUTCDate() === day;
+}
+/** Parse a leading date prefix, or null when the text does not start with one. */
+export function parseDatePrefix(content) {
+    const m = PREFIX_RE.exec(content);
+    if (!m)
+        return null;
+    const [matched, year, month, day, annotation] = m;
+    if (!isRealCalendarDay(Number(year), Number(month), Number(day)))
+        return null;
+    const trimmed = annotation === undefined ? null : annotation.trim();
+    return {
+        date: `${year}-${month}-${day}`,
+        annotation: trimmed === '' ? null : trimmed,
+        matched,
+    };
+}
+/**
+ * The dedup key: the text with its date prefix removed. The annotation comes off with the date
+ * because it records *when and in which session the line was written*, not what the line claims
+ * — the same sentence written in two sessions is one fact, and dedup has to see that.
+ */
+export function stripDatePrefix(content) {
+    const prefix = parseDatePrefix(content);
+    if (!prefix)
+        return content;
+    return content.slice(prefix.matched.length).replace(/^\s+/, '');
+}
+/** Prepend today's calendar day unless the text already carries a valid date prefix. */
+export function stampDatePrefix(content, timeZone, now = new Date()) {
+    if (parseDatePrefix(content))
+        return content;
+    return `[${calendarDate(now, timeZone)}] ${content}`;
+}

package/dist/src/tools/knowledge-graph-tools.js

@@ -200,6 +200,11 @@ Observations provide the factual foundation that supports entity existence and p
 - (!important!) **Entity must exist** - this tool only adds to existing entities
 - (!important!) Duplicates are filtered - repeating existing text with a **new** sources entry
   adds evidence to the existing revision and returns null for that position
+- (!important!) A \`[YYYY-MM-DD]\` prefix is prepended unless the text already starts with a valid
+  one. The day comes from \`RAG_MEMORY_CALENDAR_TZ\` (default UTC) - see \`calendar_timezone\` in
+  getKnowledgeGraphStats. Text may open with \`[YYYY-MM-DD note]\`; the note is treated as recording
+  metadata and is ignored when deduplicating, so the same sentence filed under two session markers
+  stays one observation
 - (!important!) Observations are cumulative. **This tool never replaces anything** - use
   correctObservation to supersede and retractObservation to withdraw
 - (!important!) **Be specific and factual** - observations should be verifiable statements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rag-memory-epf-mcp",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "engines": {
     "node": ">=24"
   },
@@ -45,7 +45,7 @@
     "prepare": "npm run build",
     "watch": "tsc --watch",
     "verify:invariants": "node test/chunk-invariants.test.mjs",
-    "verify:engine": "node test/engine-smoke.test.mjs && node test/launch-smoke.test.mjs && node test/sync-atomicity.test.mjs && node test/dedup.test.mjs && node test/search-degradation.test.mjs && node test/entity-embed-cap.test.mjs && node test/migration12.test.mjs && node test/model-cache.test.mjs && node test/embedding-gate.test.mjs && node test/lazy-boot.test.mjs && node test/reconciliation.test.mjs && node test/backfill.test.mjs && node test/fts-query.test.mjs && node test/search-contracts.test.mjs && node test/tool-contracts.test.mjs && node test/bounded-exit.test.mjs && node test/observation-schema.test.mjs && node test/observation-migration.test.mjs && node test/observation-lifecycle.test.mjs && node test/observation-contracts.test.mjs && node test/observation-search.test.mjs && node test/observation-cascade.test.mjs && node test/observation-realdata.test.mjs && node test/chunker-c.test.mjs && node test/migration14.test.mjs && node test/chunk-params-validation.test.mjs && node test/vector-reuse.test.mjs && node test/entity-range-linking.test.mjs && node test/stats-chunking.test.mjs && node test/migration14-realdata.test.mjs && node test/migration14-realdata-sync.test.mjs && node test/search-summaries-off.test.mjs && node test/document-return-contracts.test.mjs",
+    "verify:engine": "node test/engine-smoke.test.mjs && node test/launch-smoke.test.mjs && node test/sync-atomicity.test.mjs && node test/dedup.test.mjs && node test/search-degradation.test.mjs && node test/entity-embed-cap.test.mjs && node test/migration12.test.mjs && node test/model-cache.test.mjs && node test/embedding-gate.test.mjs && node test/lazy-boot.test.mjs && node test/reconciliation.test.mjs && node test/backfill.test.mjs && node test/fts-query.test.mjs && node test/search-contracts.test.mjs && node test/tool-contracts.test.mjs && node test/bounded-exit.test.mjs && node test/observation-schema.test.mjs && node test/observation-migration.test.mjs && node test/observation-lifecycle.test.mjs && node test/observation-contracts.test.mjs && node test/observation-search.test.mjs && node test/observation-cascade.test.mjs && node test/observation-realdata.test.mjs && node test/chunker-c.test.mjs && node test/migration14.test.mjs && node test/chunk-params-validation.test.mjs && node test/vector-reuse.test.mjs && node test/entity-range-linking.test.mjs && node test/stats-chunking.test.mjs && node test/migration14-realdata.test.mjs && node test/migration14-realdata-sync.test.mjs && node test/search-summaries-off.test.mjs && node test/document-return-contracts.test.mjs && node test/observation-date-prefix.test.mjs",
     "test": "npm run build && npm run verify:invariants && npm run verify:engine",
     "prepublishOnly": "npm run build && npm run verify:invariants && npm run verify:engine"
   },