@hanhnd/agent-kit 1.0.34 → 1.0.35

package/dist/services/memory/constants.js

@@ -5,7 +5,7 @@ export const DEFAULT_MEMORY_CONFIG = {
     topK: 5,
     chunkSize: 1500,
     overlapLines: 2,
-    embeddingModel: EmbeddingModelName.SMALL,
+    embeddingModel: EmbeddingModelName.BASE,
     vectorDimension: 384,
 };
 export const LOCK_RETRY_MS = 50;

package/dist/services/memory/embedder.js

@@ -50,7 +50,7 @@ export class Embedder {
             const { EmbeddingModel, FlagEmbedding } = await import('fastembed');
             const modelMap = {
                 [EmbeddingModelName.TINY]: EmbeddingModel.AllMiniLML6V2,
-                [EmbeddingModelName.SMALL]: EmbeddingModel.BGESmallENV15,
+                [EmbeddingModelName.BASE]: EmbeddingModel.BGESmallENV15,
                 [EmbeddingModelName.LARGE]: EmbeddingModel.BGEBaseENV15,
             };
             const model = modelMap[this.modelName] ?? EmbeddingModel.BGESmallENV15;

package/dist/services/memory/index.d.ts

@@ -1,5 +1,5 @@
 export { MemoryStore, StoreError } from './store.js';
 export { Embedder, EmbedderError } from './embedder.js';
 export { MemoryIndexer } from './indexer.js';
-export type { MemoryChunk, SearchResult, MemoryConfig, IndexStats } from './types.js';
+export type { MemoryChunk, SearchResult, MemoryConfig, IndexStats, SourceType, RecentSource } from './types.js';
 export { DEFAULT_MEMORY_CONFIG } from './constants.js';

package/dist/services/memory/indexer.d.ts

@@ -1,9 +1,10 @@
 import type { MemoryStore } from './store.js';
-import type { IndexStats, MemoryConfig, SearchResult } from './types.js';
+import type { IndexStats, MemoryConfig, SearchResult, SourceType } from './types.js';
 interface TextEmbedder {
     embed(texts: string[]): Promise<Float32Array[]>;
     initialize(): Promise<void>;
 }
+export declare function deriveSourceType(source: string): SourceType;
 export declare class MemoryIndexer {
     private readonly store;
     private readonly embedder;

package/dist/services/memory/indexer.js

@@ -3,6 +3,17 @@ import * as path from 'path';
 import { chunkMarkdown } from './chunker.js';
 import { LOCK_RETRY_MS, LOCK_TIMEOUT_MS, RRF_K } from './constants.js';
 import { acquireLock, releaseLock } from '../../utils/files.js';
+export function deriveSourceType(source) {
+    if (source.startsWith('compiled/provisional/conversation-digests/'))
+        return 'digest';
+    if (source.startsWith('compiled/concepts/'))
+        return 'concept';
+    if (source.startsWith('compiled/entities/'))
+        return 'entity';
+    if (source === 'compiled/preferences.md')
+        return 'preference';
+    return 'wiki';
+}
 export class MemoryIndexer {
     store;
     embedder;
@@ -27,7 +38,16 @@ export class MemoryIndexer {
             console.warn(`[memory-indexer] Cannot read file ${absolutePath}:`, err);
             return { indexed: 0, deleted: 0, skipped: existingChunkIds.size };
         }
-        const allChunks = chunkMarkdown(text, source, this.config);
+        let fileMtimeAt;
+        try {
+            fileMtimeAt = fs.statSync(absolutePath).mtimeMs;
+        }
+        catch (err) {
+            console.warn(`[memory-indexer] Cannot stat file ${absolutePath}:`, err);
+            fileMtimeAt = Date.now();
+        }
+        const sourceType = deriveSourceType(source);
+        const allChunks = chunkMarkdown(text, source, this.config, { sourceType, fileMtimeAt });
         const currentChunkIds = new Set(allChunks.map((chunk) => chunk.id));
         const toIndex = allChunks.filter((chunk) => !existingChunkIds.has(chunk.id));
         const toDelete = [...existingChunkIds].filter((id) => !currentChunkIds.has(id));
@@ -119,13 +139,9 @@ export class MemoryIndexer {
             scoreMap.set(r.id, { dense: 1 / (RRF_K + rank + 1), bm25: 0 });
         });
         bm25Results.forEach((r, rank) => {
-            const existing = scoreMap.get(r.id);
-            if (existing) {
-                existing.bm25 = 1 / (RRF_K + rank + 1);
-            }
-            else {
-                scoreMap.set(r.id, { dense: 0, bm25: 1 / (RRF_K + rank + 1) });
-            }
+            const entry = scoreMap.get(r.id) ?? { dense: 0, bm25: 0 };
+            entry.bm25 = 1 / (RRF_K + rank + 1);
+            scoreMap.set(r.id, entry);
         });
         const hasDense = this.store.vecAvailable && denseResults.length > 0;
         const numRetrievers = hasDense ? 2 : 1;

package/dist/services/memory/indexer.test.js

@@ -5,7 +5,7 @@ import { syncBuiltinESMExports } from 'node:module';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { after, before, describe, test } from 'node:test';
-import { MemoryIndexer } from './indexer.js';
+import { deriveSourceType, MemoryIndexer } from './indexer.js';
 import { MemoryStore } from './store.js';
 import { EmbeddingModelName } from './types.js';
 class StubEmbedder {
@@ -23,7 +23,7 @@ function makeConfig(wikiDir) {
         topK: 5,
         chunkSize: 1500,
         overlapLines: 2,
-        embeddingModel: EmbeddingModelName.SMALL,
+        embeddingModel: EmbeddingModelName.BASE,
         vectorDimension: 384,
     };
 }
@@ -141,11 +141,13 @@ describe('MemoryIndexer', () => {
                 {
                     id: 'stale-daily-file-0001',
                     source: '2026-05-18.md',
+                    sourceType: 'wiki',
                     heading: 'Stale',
                     headingLevel: 1,
                     content: 'pre migration content',
                     lineStart: 1,
                     lineEnd: 2,
+                    fileMtimeAt: 1,
                 },
             ], [new Float32Array(384)]);
             assert.ok(testStore.hashesBySource('2026-05-18.md').size > 0);
@@ -385,4 +387,38 @@ describe('MemoryIndexer', () => {
             fs.rmSync(testDir, { recursive: true, force: true });
         }
     });
+    test('deriveSourceType follows documented path conventions', () => {
+        assert.equal(deriveSourceType('compiled/provisional/conversation-digests/abc.md'), 'digest');
+        assert.equal(deriveSourceType('compiled/concepts/x.md'), 'concept');
+        assert.equal(deriveSourceType('compiled/entities/foo.md'), 'entity');
+        assert.equal(deriveSourceType('compiled/preferences.md'), 'preference');
+        assert.equal(deriveSourceType('compiled/preferences/something.md'), 'wiki');
+        assert.equal(deriveSourceType('raw/conv_x.md'), 'wiki');
+        assert.equal(deriveSourceType(''), 'wiki');
+    });
+    test('indexFile stamps source type and file mtime onto stored chunks', async () => {
+        const testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'index-meta-'));
+        const testCfg = makeConfig(path.join(testDir, 'wiki'));
+        const testStore = new MemoryStore(path.join(testCfg.wikiDir, 'index.db'), testCfg);
+        const testIndexer = new MemoryIndexer(testStore, new StubEmbedder(), testCfg);
+        const filePath = path.join(testCfg.wikiDir, 'compiled', 'provisional', 'conversation-digests', 'digest.md');
+        try {
+            fs.mkdirSync(path.dirname(filePath), { recursive: true });
+            fs.writeFileSync(filePath, '# Digest\nmtime metadata unique content', 'utf8');
+            const expectedMtime = fs.statSync(filePath).mtimeMs;
+            const stats = await testIndexer.indexFile(filePath);
+            assert.ok(stats.indexed > 0, `Expected indexed > 0, got ${stats.indexed}`);
+            const ids = [...testStore.hashesBySource('compiled/provisional/conversation-digests/digest.md')];
+            assert.ok(ids.length > 0);
+            const chunks = testStore.getChunksByIds(ids);
+            for (const chunk of chunks) {
+                assert.equal(chunk.sourceType, 'digest');
+                assert.equal(chunk.fileMtimeAt, expectedMtime);
+            }
+        }
+        finally {
+            testStore.close();
+            fs.rmSync(testDir, { recursive: true, force: true });
+        }
+    });
 });

package/dist/services/memory/memory.test.js

@@ -1,4 +1,7 @@
 import * as assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import { describe, test } from 'node:test';
 import { EmbeddingModelName } from './types.js';
 import { resolveMemoryConfig } from '../../core/config/index.js';
@@ -6,22 +9,26 @@ import { registerMemoryTools } from '../../mcp/memory.js';
 // Minimal McpServer stub that captures tool registrations
 function makeMockServer() {
     const tools = new Map();
+    const descriptions = new Map();
     const server = {
-        tool(name, _desc, _schema, handler) {
+        tool(name, desc, _schema, handler) {
+            descriptions.set(name, desc);
             tools.set(name, handler);
         },
     };
-    return { server, tools };
+    return { server, tools, descriptions };
 }
 function makeChunk(overrides = {}) {
     return {
         id: 'test-id-abc123',
         source: '2024-01-01.md',
+        sourceType: 'wiki',
         heading: 'My Section',
         headingLevel: 2,
         content: 'This is the chunk content.',
         lineStart: 1,
         lineEnd: 5,
+        fileMtimeAt: 1000,
         ...overrides,
     };
 }
@@ -31,7 +38,7 @@ const BASE_CONFIG = {
     topK: 5,
     chunkSize: 1500,
     overlapLines: 2,
-    embeddingModel: EmbeddingModelName.SMALL,
+    embeddingModel: EmbeddingModelName.BASE,
     vectorDimension: 384,
 };
 function makeIndexerStub(overrides = {}) {
@@ -40,8 +47,11 @@ function makeIndexerStub(overrides = {}) {
         save: overrides.save ?? (async () => ({ indexed: 1, deleted: 0, skipped: 0 })),
     };
 }
-function makeStoreStub(vecAvailable) {
-    return { vecAvailable };
+function makeStoreStub(vecAvailable, overrides = {}) {
+    return {
+        vecAvailable,
+        getRecentSources: overrides.getRecentSources ?? (() => []),
+    };
 }
 function extractText(result) {
     const r = result;
@@ -62,7 +72,8 @@ describe('kit_memory_search', () => {
         const indexer = makeIndexerStub({ search: async () => [searchResult] });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+        registerMemoryTools(server, '/tmp', {
+            settings: { memory: { enabled: true } },
             indexer,
             store,
             config: BASE_CONFIG,
@@ -78,7 +89,8 @@ describe('kit_memory_search', () => {
         const indexer = makeIndexerStub({ search: async () => [] });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+        registerMemoryTools(server, '/tmp', {
+            settings: { memory: { enabled: true } },
             indexer,
             store,
             config: BASE_CONFIG,
@@ -91,7 +103,8 @@ describe('kit_memory_search', () => {
         const indexer = makeIndexerStub({ search: async () => [] });
         const store = makeStoreStub(false);
         const { server, tools } = makeMockServer();
-        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+        registerMemoryTools(server, '/tmp', {
+            settings: { memory: { enabled: true } },
             indexer,
             store,
             config: BASE_CONFIG,
@@ -111,7 +124,8 @@ describe('kit_memory_search', () => {
         const indexer = makeIndexerStub({ search: async () => [searchResult] });
         const store = makeStoreStub(false);
         const { server, tools } = makeMockServer();
-        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+        registerMemoryTools(server, '/tmp', {
+            settings: { memory: { enabled: true } },
             indexer,
             store,
             config: BASE_CONFIG,
@@ -132,7 +146,8 @@ describe('kit_memory_search', () => {
         const indexer = makeIndexerStub({ search: async () => [searchResult] });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+        registerMemoryTools(server, '/tmp', {
+            settings: { memory: { enabled: true } },
             indexer,
             store,
             config: BASE_CONFIG,
@@ -152,7 +167,8 @@ describe('kit_memory_search', () => {
         });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+        registerMemoryTools(server, '/tmp', {
+            settings: { memory: { enabled: true } },
             indexer,
             store,
             config: BASE_CONFIG,
@@ -170,7 +186,8 @@ describe('kit_memory_search', () => {
         });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+        registerMemoryTools(server, '/tmp', {
+            settings: { memory: { enabled: true } },
             indexer,
             store,
             config: BASE_CONFIG,
@@ -186,7 +203,8 @@ describe('kit_memory_search', () => {
         });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+        registerMemoryTools(server, '/tmp', {
+            settings: { memory: { enabled: true } },
             indexer,
             store,
             config: BASE_CONFIG,
@@ -196,6 +214,143 @@ describe('kit_memory_search', () => {
         assert.ok(text.includes('kit_memory_search failed'), `Expected error prefix, got: ${text}`);
         assert.ok(text.includes('search exploded'), `Expected error message, got: ${text}`);
     });
+    test('description routes factual and temporal queries distinctly', () => {
+        const indexer = makeIndexerStub();
+        const store = makeStoreStub(true);
+        const { server, descriptions } = makeMockServer();
+        registerMemoryTools(server, '/tmp', {
+            settings: { memory: { enabled: true } },
+            indexer,
+            store,
+            config: BASE_CONFIG,
+        });
+        const description = descriptions.get('kit_memory_search') ?? '';
+        assert.match(description, /factual|semantic/);
+        assert.match(description, /kit_memory_recent/);
+        assert.match(description, /keywords/);
+        assert.match(description, /stopwords/);
+    });
+});
+describe('kit_memory_recent', () => {
+    test('returns recent sources ordered by store recency result', async () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'memory-recent-digest-'));
+        const wikiDir = path.join(tmpDir, 'wiki');
+        const olderSource = 'compiled/provisional/conversation-digests/older.md';
+        const newerSource = 'compiled/provisional/conversation-digests/newer.md';
+        const entitySource = 'compiled/entities/entity.md';
+        try {
+            fs.mkdirSync(path.join(wikiDir, 'compiled', 'provisional', 'conversation-digests'), { recursive: true });
+            fs.mkdirSync(path.join(wikiDir, 'compiled', 'entities'), { recursive: true });
+            fs.writeFileSync(path.join(wikiDir, olderSource), '# Older\nolder content', 'utf8');
+            fs.writeFileSync(path.join(wikiDir, newerSource), '# Newer\nnewer content', 'utf8');
+            fs.writeFileSync(path.join(wikiDir, entitySource), '# Entity\nentity content', 'utf8');
+            const calls = [];
+            const store = makeStoreStub(true, {
+                getRecentSources: (options) => {
+                    calls.push(options);
+                    return [
+                        { source: entitySource, fileMtimeAt: 300 },
+                        { source: newerSource, fileMtimeAt: 200 },
+                        { source: olderSource, fileMtimeAt: 100 },
+                    ];
+                },
+            });
+            const { server, tools } = makeMockServer();
+            registerMemoryTools(server, tmpDir, {
+                settings: { memory: { enabled: true } },
+                indexer: makeIndexerStub(),
+                store,
+                config: { ...BASE_CONFIG, wikiDir },
+            });
+            const result = await tools.get('kit_memory_recent')({ n: 2 });
+            const text = extractText(result);
+            assert.deepEqual(calls, [{ limit: 2, sourceType: undefined }]);
+            assert.ok(text.indexOf('entity.md') < text.indexOf('newer.md'));
+            assert.ok(text.includes('# Entity\nentity content'));
+            assert.ok(text.includes('# Newer\nnewer content'));
+        }
+        finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+    test('passes optional source type filter to recent lookup', async () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'memory-recent-filter-'));
+        const wikiDir = path.join(tmpDir, 'wiki');
+        const digestSource = 'compiled/provisional/conversation-digests/digest.md';
+        try {
+            fs.mkdirSync(path.join(wikiDir, 'compiled', 'provisional', 'conversation-digests'), { recursive: true });
+            fs.writeFileSync(path.join(wikiDir, digestSource), '# Digest\nfiltered content', 'utf8');
+            const calls = [];
+            const store = makeStoreStub(true, {
+                getRecentSources: (options) => {
+                    calls.push(options);
+                    return [{ source: digestSource, fileMtimeAt: 100 }];
+                },
+            });
+            const { server, tools } = makeMockServer();
+            registerMemoryTools(server, tmpDir, {
+                settings: { memory: { enabled: true } },
+                indexer: makeIndexerStub(),
+                store,
+                config: { ...BASE_CONFIG, wikiDir },
+            });
+            const result = await tools.get('kit_memory_recent')({ source_type: 'digest' });
+            const text = extractText(result);
+            assert.deepEqual(calls, [{ limit: 5, sourceType: 'digest' }]);
+            assert.ok(text.includes('provisional/conversation-digests/digest.md'));
+            assert.ok(text.includes('filtered content'));
+        }
+        finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+    test('skips missing files without source-unavailable warning', async () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'memory-recent-missing-'));
+        const wikiDir = path.join(tmpDir, 'wiki');
+        const presentSource = 'compiled/entities/present.md';
+        try {
+            fs.mkdirSync(path.join(wikiDir, 'compiled', 'entities'), { recursive: true });
+            fs.writeFileSync(path.join(wikiDir, presentSource), '# Present\navailable content', 'utf8');
+            const store = makeStoreStub(true, {
+                getRecentSources: () => [
+                    { source: 'compiled/entities/missing.md', fileMtimeAt: 200 },
+                    { source: presentSource, fileMtimeAt: 100 },
+                ],
+            });
+            const { server, tools } = makeMockServer();
+            registerMemoryTools(server, tmpDir, {
+                settings: { memory: { enabled: true } },
+                indexer: makeIndexerStub(),
+                store,
+                config: { ...BASE_CONFIG, wikiDir },
+            });
+            const result = await tools.get('kit_memory_recent')({});
+            const text = extractText(result);
+            assert.ok(!text.includes('missing.md'));
+            assert.ok(!text.includes('Source file unavailable'));
+            assert.ok(text.includes('available content'));
+        }
+        finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+    test('is registered only when memory is enabled and description mentions temporal routing', () => {
+        const enabledServer = makeMockServer();
+        registerMemoryTools(enabledServer.server, '/tmp', {
+            settings: { memory: { enabled: true } },
+            indexer: makeIndexerStub(),
+            store: makeStoreStub(true),
+            config: BASE_CONFIG,
+        });
+        assert.ok(enabledServer.tools.has('kit_memory_recent'));
+        assert.match(enabledServer.descriptions.get('kit_memory_recent') ?? '', /last session|recent/);
+        const disabledServer = makeMockServer();
+        const result = registerMemoryTools(disabledServer.server, '/tmp', {
+            settings: { memory: { enabled: false } },
+        });
+        assert.equal(result, null);
+        assert.equal(disabledServer.tools.has('kit_memory_recent'), false);
+    });
 });
 describe('kit_memory_save', () => {
     test('returns saved:true and queued-for-compile status on success', async () => {
@@ -204,7 +359,8 @@ describe('kit_memory_save', () => {
         });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+        registerMemoryTools(server, '/tmp', {
+            settings: { memory: { enabled: true } },
             indexer,
             store,
             config: BASE_CONFIG,
@@ -224,7 +380,8 @@ describe('kit_memory_save', () => {
         });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+        registerMemoryTools(server, '/tmp', {
+            settings: { memory: { enabled: true } },
             indexer,
             store,
             config: BASE_CONFIG,

package/dist/services/memory/store.d.ts

@@ -1,4 +1,5 @@
-import type { MemoryChunk, MemoryConfig } from './types.js';
+import type { MemoryChunk, MemoryConfig, RecentSource, SourceType } from './types.js';
+export declare const SCHEMA_VERSION = 2;
 export declare class StoreError extends Error {
     constructor(message: string, cause?: unknown);
 }
@@ -13,6 +14,10 @@ export declare class MemoryStore {
     upsert(chunks: MemoryChunk[], embeddings: Float32Array[]): void;
     hashesBySource(source: string): Set<string>;
     indexedSources(): string[];
+    getRecentSources(options: {
+        limit: number;
+        sourceType?: SourceType;
+    }): RecentSource[];
     deleteBySource(source: string): void;
     deleteByIds(ids: string[]): void;
     searchDense(embedding: Float32Array, limit: number): Array<{