v1.3.2: unified search, session pagination, preview fix, Cursor docs

Author: keshrath

docs/SETUP.md

@@ -234,32 +234,69 @@ Combine with `AGENTS.md` instructions (see below).
 
 ### Cursor and Windsurf
 
-Cursor and Windsurf don't support lifecycle hooks. Use the client's system prompt / instructions file:
+Cursor and Windsurf don't support lifecycle hooks. Use rules files instead:
 
-| Client   | Instructions file |
-| -------- | ----------------- |
-| Cursor   | `.cursorrules`    |
-| Windsurf | `.windsurfrules`  |
+| Client   | Rules location        |
+| -------- | --------------------- |
+| Cursor   | `.cursor/rules/*.mdc` |
+| Windsurf | `.windsurfrules`      |
 
-Add these instructions:
+#### Cursor Rules Setup
 
+Create `.cursor/rules/agent-mcp-stack.mdc` with "Always Apply" mode:
+
+```yaml
+---
+description: Agent MCP stack integration
+globs: *
+alwaysApply: true
+---
+
+# Agent MCP Stack
+
+## Default behavior in every chat
+
+Treat `agent-comm`, `agent-knowledge`, and `agent-tasks` as default infrastructure
+for this repository. Do not wait for the user to restate this.
+
+At the start of each new chat/session:
+
+1. Bootstrap `agent-comm` (`comm_register`, join `general`, send one-line intent, then `comm_inbox`).
+2. Use `agent-knowledge` first for recall/session context when it can help
+   (especially prior decisions, errors, tool usage, and related sessions).
+3. Check `agent-tasks` before creating work (`task_list`), and keep task
+   state/artifacts/comments current when work spans more than one step.
+
+If an MCP server is unavailable, report it briefly and continue with local tools;
+retry MCP usage after restoring connectivity.
 ```
-You have access to agent-knowledge MCP tools — a shared knowledge base synced via git.
 
-Available tools: knowledge_list, knowledge_read, knowledge_write, knowledge_search,
-knowledge_recall, knowledge_sessions, knowledge_config, knowledge_sync,
-knowledge_link, knowledge_unlink, knowledge_links, knowledge_graph
+Optionally create `.cursor/rules/session-wrapup-knowledge.mdc` for session wrap-up:
+
+```yaml
+---
+description: Save session learnings to knowledge base
+globs: *
+alwaysApply: false
+---
 
-Categories: projects, people, decisions, workflows, notes
+# Session Wrap-up
 
-Use knowledge_search for semantic + keyword search across all entries.
-Use knowledge_recall for scoped search (errors, plans, configs, tools, files, decisions).
-Use knowledge_link/knowledge_unlink to manage relationships between entries.
-Use knowledge_graph to explore connections from any entry via BFS traversal.
+Before ending a session, save non-obvious learnings to agent-knowledge:
 
-Dashboard: http://localhost:3423
+1. `knowledge_search` for existing entries that overlap with this session's work.
+2. `knowledge_write` new entries for decisions, architecture changes, or error patterns
+   that aren't already captured.
+3. `knowledge_link` related entries together.
+
+Categories: projects (project context), decisions (trade-offs made), workflows (processes),
+notes (everything else).
 ```
 
+#### Windsurf
+
+Add equivalent instructions to `.windsurfrules` in your project root.
+
 ---
 
 ## Knowledge Base Setup
@@ -457,11 +494,11 @@ If your session data is in a non-standard location, use `EXTRA_SESSION_ROOTS` to
 
 ## Client Comparison
 
-| Feature              | Claude Code | Cursor       | OpenCode      | Cline      | Continue.dev | Aider          | Windsurf       |
-| -------------------- | ----------- | ------------ | ------------- | ---------- | ------------ | -------------- | -------------- |
-| MCP stdio transport  | Yes         | Yes          | Yes           | Yes        | Yes          | --             | Yes            |
-| Session reading      | Yes (JSONL) | Yes (JSONL)  | Yes (SQLite)  | Yes (JSON) | Yes (JSON)   | Yes (MD/JSONL) | --             |
-| Lifecycle hooks      | Yes (JSON)  | No           | Yes (plugins) | No         | No           | --             | No             |
-| Session auto-distill | Yes         | Yes          | Yes           | Yes        | Yes          | Yes            | --             |
-| System prompt file   | CLAUDE.md   | .cursorrules | AGENTS.md     | --         | --           | --             | .windsurfrules |
-| REST API fallback    | Yes         | Yes          | Yes           | Yes        | Yes          | Yes            | Yes            |
+| Feature              | Claude Code | Cursor               | OpenCode      | Cline      | Continue.dev | Aider          | Windsurf       |
+| -------------------- | ----------- | -------------------- | ------------- | ---------- | ------------ | -------------- | -------------- |
+| MCP stdio transport  | Yes         | Yes                  | Yes           | Yes        | Yes          | --             | Yes            |
+| Session reading      | Yes (JSONL) | Yes (JSONL)          | Yes (SQLite)  | Yes (JSON) | Yes (JSON)   | Yes (MD/JSONL) | --             |
+| Lifecycle hooks      | Yes (JSON)  | No                   | Yes (plugins) | No         | No           | --             | No             |
+| Session auto-distill | Yes         | Yes                  | Yes           | Yes        | Yes          | Yes            | --             |
+| System prompt file   | CLAUDE.md   | .cursor/rules/\*.mdc | AGENTS.md     | --         | --           | --             | .windsurfrules |
+| REST API fallback    | Yes         | Yes                  | Yes           | Yes        | Yes          | Yes            | Yes            |

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-knowledge",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Cross-session memory and recall for AI agents — git-synced knowledge base, knowledge graph, confidence scoring, hybrid semantic+TF-IDF search, auto-distillation with secrets scrubbing",
   "type": "module",
   "main": "dist/index.js",

package.json

@@ -68,10 +68,9 @@ export function createServer(options?: ServerOptions): Server {
       {
         name: 'knowledge_search',
         description:
-          'Hybrid semantic + TF-IDF search across session conversations. ' +
-          'Results ranked by blended relevance (semantic similarity + keyword match) x recency. ' +
-          'When "scope" is provided, searches within a specific domain (errors, plans, configs, tools, files, decisions). ' +
-          'Without scope, performs general search across all sessions.',
+          'Search across sessions AND knowledge entries. ' +
+          'Returns both session matches (semantic + TF-IDF) and knowledge base matches. ' +
+          'When "scope" is provided, searches within a specific domain (errors, plans, configs, tools, files, decisions) in sessions only.',
         inputSchema: {
           type: 'object' as const,
           properties: {
@@ -144,6 +143,14 @@ export function createServer(options?: ServerOptions): Server {
               type: 'number',
               description: 'Only return the last N messages (action=get)',
             },
+            limit: {
+              type: 'number',
+              description: 'Max sessions to return (action=list, default: 20, max: 500)',
+            },
+            offset: {
+              type: 'number',
+              description: 'Skip first N sessions (action=list, default: 0)',
+            },
           },
           required: ['action'],
         },

src/server.ts

@@ -1,4 +1,5 @@
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import { getConfig } from '../types.js';
 import { getAvailableAdapters } from './adapters/index.js';
@@ -191,21 +192,21 @@ export function getSessionMeta(entries: SessionEntry[]): SessionMeta {
  * Falls back to the raw name if it doesn't match the expected pattern.
  */
 function decodeProjectDirName(dirName: string): string {
-  const parts = dirName.split('--');
-  if (parts.length < 2) return dirName;
-
-  if (!/^[A-Z]$/i.test(parts[0])) return dirName;
+  const homeParts = os.homedir().replace(/\\/g, '/').split('/');
+  const homeEncoded = homeParts[0].replace(':', '') + '--' + homeParts.slice(1).join('-');
 
-  const homeIdx = parts.findIndex((p) => /^(users|home)-/i.test(p));
+  if (dirName === homeEncoded) return '~';
 
-  if (homeIdx >= 0 && homeIdx < parts.length - 1) {
-    return parts.slice(homeIdx + 1).join('/');
+  if (dirName.startsWith(homeEncoded + '--')) {
+    return dirName.slice(homeEncoded.length + 2).replace(/--/g, '/');
   }
 
-  if (homeIdx >= 0 && homeIdx === parts.length - 1) {
-    return '~';
+  if (dirName.startsWith(homeEncoded + '-')) {
+    return dirName.slice(homeEncoded.length + 1).replace(/--/g, '/');
   }
 
+  const parts = dirName.split('--');
+  if (parts.length < 2) return dirName;
   return parts[parts.length - 1];
 }
 

src/sessions/parser.ts

@@ -207,24 +207,31 @@ function fastMeta(filePath: string): SessionMeta | null {
     }
     fs.closeSync(fd);
 
+    const extractText = (content: unknown): string => {
+      if (typeof content === 'string') return content;
+      if (Array.isArray(content)) {
+        const parts = content
+          .filter(
+            (p) =>
+              typeof p === 'string' || (typeof p === 'object' && p !== null && p.type === 'text'),
+          )
+          .map((p) => (typeof p === 'string' ? p : p.text));
+        return parts.length > 0 ? parts.join('\n') : '';
+      }
+      return '';
+    };
+
     let preview = '';
+    let userMessageCount = 0;
     for (const line of headLines) {
       try {
         const entry = JSON.parse(line);
-        if (entry.type === 'user' && entry.message?.role === 'user') {
-          const content = entry.message.content;
-          if (typeof content === 'string') {
-            preview = content.substring(0, 200);
-            break;
-          }
-          if (Array.isArray(content)) {
-            const textBlock = content.find(
-              (b: { type: string; text?: string }) => b.type === 'text' && b.text,
-            );
-            if (textBlock) {
-              preview = textBlock.text.substring(0, 200);
-              break;
-            }
+        const role = entry.type ?? entry.role;
+        if (role === 'user') {
+          userMessageCount++;
+          if (!preview && entry.message?.content !== null && entry.message?.content !== undefined) {
+            const text = extractText(entry.message.content);
+            if (text) preview = text.substring(0, 200);
           }
         }
       } catch {
@@ -238,7 +245,7 @@ function fastMeta(filePath: string): SessionMeta | null {
       cwd: (first.cwd as string) || '',
       branch: (first.gitBranch as string) || '',
       messageCount: Math.max(1, Math.round(stat.size / 500)),
-      userMessageCount: 0,
+      userMessageCount,
       preview,
     };
   } catch {

src/sessions/summary.ts

@@ -14,6 +14,7 @@ import { consolidate } from './knowledge/consolidate.js';
 import { reflect } from './knowledge/reflect.js';
 import { indexKnowledgeEntry } from './sessions/indexer.js';
 import { searchSessions } from './sessions/search.js';
+import { searchKnowledge } from './knowledge/search.js';
 import { listSessions, getSessionSummary } from './sessions/summary.js';
 import { scopedSearch, type SearchScope } from './sessions/scopes.js';
 import { VectorStore } from './vectorstore/index.js';
@@ -253,8 +254,12 @@ export function handleKnowledgeSession(
   switch (action) {
     case 'list': {
       const project = optionalString(a, 'project');
-      const sessions = listSessions(project);
-      return ok(sessions);
+      const limit = optionalNumber(a, 'limit', 1, 500) ?? 20;
+      const offset = optionalNumber(a, 'offset', 0, 100000) ?? 0;
+      let sessions = listSessions(project);
+      const total = sessions.length;
+      sessions = sessions.slice(offset, offset + limit);
+      return ok({ total, offset, limit, sessions });
     }
     case 'get': {
       const sessionId = requireString(a, 'session_id');
@@ -323,18 +328,32 @@ export async function handleKnowledgeSearch(args: Record<string, unknown>): Prom
     return ok(results);
   }
 
-  // General search
+  // General search — sessions + knowledge entries
   const role =
     validateEnum(optionalString(a, 'role'), ['user', 'assistant', 'all'] as const, 'role') ?? 'all';
   const ranked = optionalBoolean(a, 'ranked') ?? true;
-  const results = await searchSessions(query, {
+  const sessionResults = await searchSessions(query, {
     project,
     role,
     maxResults,
     ranked,
     semantic,
   });
-  return ok(results);
+
+  const config = getConfig();
+  const knowledgeResults = searchKnowledge(config.memoryDir, query, { maxResults: 10 }).map(
+    (r) => ({
+      source: 'knowledge' as const,
+      id: r.entry.path,
+      path: r.entry.path,
+      category: r.entry.category,
+      title: r.entry.title || r.entry.path,
+      excerpt: r.excerpt,
+      score: r.score,
+    }),
+  );
+
+  return ok({ sessions: sessionResults, knowledge: knowledgeResults });
 }
 
 export function handleKnowledgeAdmin(args: Record<string, unknown>): ToolResult {