- Orchestrator, memory tools, context loader and pattern write-back use a MemoryStore and a workspace scope instead of MindDB layers; the knowledge graph tools, cognify, memory linker and feedback handler are gone (graph hidden in v1, ADR-0002). - The server opens one mem0 store in <dataDir>/memory/, embedded by the in-process model on first use, and extracts facts about the user in the background with the model the user chose (memoryExtraction setting). - Legacy .mind memories are copied into the store once, in the background; the legacy files are only read. - Weaver consolidation, harvest, wiki, memory import, memory lanes, vector backfill and index reconciliation are removed; agent runs, loops, sub-agent results, connector fetch and the failed-turn capture write through the contract. Workspace sessions no longer hold a mind handle. - FileIndexer and the install audit move to waggle.db; recall date helpers and the reranker are copied into core. - The CLI REPL opens the same memory store.
469 lines
21 KiB
TypeScript
469 lines
21 KiB
TypeScript
import {
|
||
PERSONAL_SCOPE,
|
||
workspaceScope,
|
||
MEMORY_IMPORTANCE,
|
||
MEMORY_SOURCES,
|
||
type MemoryHit,
|
||
type MemoryImportance,
|
||
type MemoryKind,
|
||
type MemoryScope,
|
||
type MemorySource,
|
||
type MemoryStore,
|
||
} from '@waggle/memory-contract';
|
||
import type { IdentityLayer, AwarenessLayer } from '@waggle/core';
|
||
import type { RiskLevel } from '@waggle/shared';
|
||
import { createCoreLogger } from '@waggle/core';
|
||
import { detectContradiction } from './contradiction-detector.js';
|
||
import { scanForInjection } from './injection-scanner.js';
|
||
import { normalizeForDedup, detectDramaticClaims, deriveConfidence, type ConfidenceLevel } from './text-analysis.js';
|
||
export type { ConfidenceLevel } from './text-analysis.js';
|
||
export { formatCombinedResult } from './result-formatter.js';
|
||
|
||
const log = createCoreLogger('mind-tools');
|
||
|
||
export interface ToolDefinition {
|
||
name: string;
|
||
description: string;
|
||
parameters: Record<string, unknown>;
|
||
execute: (args: Record<string, unknown>) => Promise<string>;
|
||
/**
|
||
* Provider-authored runtime risk. This is trusted metadata, never model input;
|
||
* confirmation policy may use it only to elevate name-based risk.
|
||
*/
|
||
riskLevel?: RiskLevel;
|
||
/** PM-6: Whether this tool can operate without LLM connectivity (default: false) */
|
||
offlineCapable?: boolean;
|
||
/**
|
||
* Dynamic availability check — called before each agent turn to decide
|
||
* whether this tool should be included in the tool list.
|
||
* Return false to hide the tool (e.g., browser not connected, no git repo).
|
||
* If not provided, the tool is always available.
|
||
*/
|
||
checkAvailability?: () => boolean;
|
||
}
|
||
|
||
/** Tracks tool utilization across the current session */
|
||
export interface ToolUtilizationTracker {
|
||
/** Record that a tool was used */
|
||
recordUsage(toolName: string): void;
|
||
/** Get the set of unique tools used this session */
|
||
getUsedTools(): Set<string>;
|
||
/** Get the total number of available tools */
|
||
totalAvailable: number;
|
||
/** Get utilization ratio (uniqueUsed / totalAvailable) */
|
||
getUtilization(): number;
|
||
}
|
||
|
||
/** Create a ToolUtilizationTracker instance */
|
||
export function createToolUtilizationTracker(totalAvailable: number): ToolUtilizationTracker {
|
||
const usedTools = new Set<string>();
|
||
return {
|
||
recordUsage(toolName: string) {
|
||
usedTools.add(toolName);
|
||
},
|
||
getUsedTools() {
|
||
return new Set(usedTools);
|
||
},
|
||
totalAvailable,
|
||
getUtilization() {
|
||
if (totalAvailable === 0) return 0;
|
||
return usedTools.size / totalAvailable;
|
||
},
|
||
};
|
||
}
|
||
|
||
|
||
export interface MindToolDeps {
|
||
memory: MemoryStore;
|
||
identity: IdentityLayer;
|
||
awareness: AwarenessLayer;
|
||
/** Active workspace, checked at call time; null when only personal memory is active. */
|
||
getWorkspaceId?: () => string | null;
|
||
/** W5.7: workspaces searched by search_all_workspaces. */
|
||
listWorkspaces?: () => Array<{ id: string; name: string }>;
|
||
/** Optional tool utilization tracker for session-level stats */
|
||
toolUtilizationTracker?: ToolUtilizationTracker;
|
||
/**
|
||
* Review C2: externally-owned save counter so the rate limit survives
|
||
* tool-array reconstruction (persona switch, workspace change, MCP reconnect).
|
||
* If omitted, a local counter is used (legacy behavior).
|
||
*/
|
||
saveCounter?: { count: number };
|
||
}
|
||
|
||
/** Kinds the agent may choose when it saves a memory. */
|
||
const SAVE_KINDS: readonly MemoryKind[] = ['fact', 'preference', 'decision', 'event', 'note'];
|
||
|
||
/** Recent memories compared against a new one for contradictions. */
|
||
const CONTRADICTION_WINDOW = 50;
|
||
/** Search hits compared against a new memory for normalized duplicates. */
|
||
const DEDUP_CANDIDATES = 20;
|
||
|
||
function formatHit(hit: MemoryHit, index: number): string {
|
||
return `[${index + 1}] (score: ${hit.score.toFixed(3)}, date: ${hit.createdAt.slice(0, 10)}, kind: ${hit.kind}, importance: ${hit.importance}, source: ${hit.source})\n${hit.text}`;
|
||
}
|
||
|
||
export function createMindTools(deps: MindToolDeps): ToolDefinition[] {
|
||
// W2.10: Per-session memory save rate limiter (prevents memory flooding attacks)
|
||
// Review C2: use externally-owned counter when provided so limit survives
|
||
// tool-array reconstruction (persona switch, workspace change, MCP reconnect).
|
||
const MAX_SAVES_PER_SESSION = 50;
|
||
const saveCounter = deps.saveCounter ?? { count: 0 };
|
||
const activeWorkspace = (): MemoryScope | null => {
|
||
const id = deps.getWorkspaceId?.() ?? null;
|
||
return id ? workspaceScope(id) : null;
|
||
};
|
||
|
||
return [
|
||
{
|
||
name: 'get_identity',
|
||
description: 'Get the agent identity (who am I, what is my role)',
|
||
offlineCapable: true,
|
||
parameters: {},
|
||
execute: async () => {
|
||
if (!deps.identity.exists()) return 'No identity configured yet.';
|
||
return deps.identity.toContext();
|
||
},
|
||
},
|
||
{
|
||
name: 'get_awareness',
|
||
description: 'Get current awareness state (active tasks, recent actions, pending items, flags, tool utilization)',
|
||
offlineCapable: true,
|
||
parameters: {},
|
||
execute: async () => {
|
||
let context = deps.awareness.toContext();
|
||
|
||
// Append utilization stats if tracker is available
|
||
if (deps.toolUtilizationTracker) {
|
||
const tracker = deps.toolUtilizationTracker;
|
||
const used = tracker.getUsedTools();
|
||
const utilization = tracker.getUtilization();
|
||
context += `\n\n## Tool Utilization\n`;
|
||
context += `- Unique tools used this session: ${used.size}\n`;
|
||
context += `- Total available tools: ${tracker.totalAvailable}\n`;
|
||
context += `- Utilization: ${(utilization * 100).toFixed(1)}%\n`;
|
||
if (utilization < 0.1) {
|
||
context += `- Note: Low utilization — consider using more of your available tools (skills, workflows, sub-agents) for richer results.\n`;
|
||
}
|
||
}
|
||
|
||
return context;
|
||
},
|
||
},
|
||
{
|
||
name: 'search_memory',
|
||
description: 'Search through memory for relevant past experiences and knowledge. Searches both personal and workspace memory when a workspace is active.',
|
||
offlineCapable: true,
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {
|
||
query: { type: 'string', description: 'What to search for' },
|
||
scope: {
|
||
type: 'string',
|
||
enum: ['all', 'personal', 'workspace'],
|
||
description: 'Which memory to search (default: all)',
|
||
},
|
||
limit: { type: 'number', description: 'Max results to return' },
|
||
importance: {
|
||
type: 'string',
|
||
enum: ['critical', 'important', 'normal', 'temporary', 'all'],
|
||
description: 'Filter by importance level (default: all)',
|
||
},
|
||
since: {
|
||
type: 'string',
|
||
description: 'ISO date — only return memories created after this date (e.g., "2026-03-14")',
|
||
},
|
||
until: {
|
||
type: 'string',
|
||
description: 'ISO date — only return memories created before this date (e.g., "2026-03-21")',
|
||
},
|
||
},
|
||
required: ['query'],
|
||
},
|
||
execute: async (args) => {
|
||
const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 10;
|
||
const scope = (args.scope as string) ?? 'all';
|
||
const query = String(args.query ?? '');
|
||
const importanceFilter = (args.importance as string) ?? 'all';
|
||
// F20: Temporal filtering params
|
||
const since = typeof args.since === 'string' ? args.since : undefined;
|
||
const until = typeof args.until === 'string' ? args.until : undefined;
|
||
const ws = activeWorkspace();
|
||
|
||
// F14: exact importance filter, applied after ranking
|
||
const byImportance = (hits: MemoryHit[]): MemoryHit[] =>
|
||
importanceFilter === 'all' ? hits : hits.filter(h => h.importance === importanceFilter);
|
||
const search = (target: MemoryScope, max: number): Promise<MemoryHit[]> =>
|
||
deps.memory.search(query, {
|
||
scopes: [target],
|
||
limit: importanceFilter === 'all' ? max : max * 5,
|
||
...(since && { since }),
|
||
...(until && { until: until.length === 10 ? `${until}T23:59:59.999Z` : until }),
|
||
});
|
||
|
||
const sections: string[] = [];
|
||
|
||
// W2.6: Search workspace memory FIRST (results shown before personal)
|
||
if (ws && (scope === 'all' || scope === 'workspace')) {
|
||
const wsResults = byImportance(await search(ws, limit)).slice(0, limit);
|
||
if (wsResults.length > 0) {
|
||
sections.push('## Workspace Memory');
|
||
sections.push(...wsResults.map(formatHit));
|
||
}
|
||
}
|
||
|
||
// Search personal memory (with reduced limit when a workspace is active)
|
||
if (scope === 'all' || scope === 'personal') {
|
||
// W2.6: When inside a workspace, cap personal results to reduce noise
|
||
const personalLimit = (ws && scope === 'all') ? Math.min(limit, 3) : limit;
|
||
const personalResults = byImportance(await search(PERSONAL_SCOPE, personalLimit)).slice(0, personalLimit);
|
||
if (personalResults.length > 0) {
|
||
if (ws) {
|
||
sections.push('## Personal Memory\n_(Cross-workspace — not specific to this workspace)_');
|
||
}
|
||
sections.push(...personalResults.map(formatHit));
|
||
}
|
||
}
|
||
|
||
// W2.5: Detect potential contradictions in results
|
||
if (sections.length > 1) {
|
||
const allContent = sections.filter(s => !s.startsWith('##')).join('\n');
|
||
const contradictionSignals = ['but ', 'however', 'instead', 'no longer', 'changed to', 'reversed', 'cancelled', 'not '];
|
||
const hasConflictSignal = contradictionSignals.some(s => allContent.toLowerCase().includes(s));
|
||
if (hasConflictSignal) {
|
||
sections.push('\n⚠️ Note: Multiple memories found. Check for potential contradictions — verify which is the most current/authoritative version.');
|
||
}
|
||
}
|
||
|
||
if (sections.length === 0) return 'No relevant memories found.';
|
||
return sections.join('\n\n');
|
||
},
|
||
},
|
||
// W5.7: Cross-workspace search — searches ALL workspaces + personal
|
||
{
|
||
name: 'search_all_workspaces',
|
||
description: 'Search across ALL workspaces and personal memory simultaneously. Use for cross-project queries like "what should I work on?" or "find everything about topic X across all projects".',
|
||
offlineCapable: true,
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {
|
||
query: { type: 'string', description: 'What to search for across all workspaces' },
|
||
limit: { type: 'number', description: 'Max results per workspace (default: 5)' },
|
||
},
|
||
required: ['query'],
|
||
},
|
||
execute: async (args) => {
|
||
const query = String(args.query ?? '');
|
||
const limitPerWs = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 5;
|
||
const sections: string[] = [];
|
||
const short = (hit: MemoryHit, i: number): string =>
|
||
`[${i + 1}] (score: ${hit.score.toFixed(3)}, importance: ${hit.importance})\n${hit.text}`;
|
||
|
||
const personalResults = await deps.memory.search(query, { scopes: [PERSONAL_SCOPE], limit: limitPerWs });
|
||
if (personalResults.length > 0) {
|
||
sections.push('## Personal Memory');
|
||
sections.push(...personalResults.map(short));
|
||
}
|
||
|
||
for (const { id, name } of deps.listWorkspaces?.() ?? []) {
|
||
try {
|
||
const wsResults = await deps.memory.search(query, { scopes: [workspaceScope(id)], limit: limitPerWs });
|
||
if (wsResults.length > 0) {
|
||
sections.push(`## Workspace: ${name} (${id})`);
|
||
sections.push(...wsResults.map(short));
|
||
}
|
||
} catch (err) { log.warn(`search_all_workspaces: skipped workspace ${id}`, err); }
|
||
}
|
||
|
||
if (sections.length === 0) return 'No relevant memories found across any workspace.';
|
||
return sections.join('\n\n');
|
||
},
|
||
},
|
||
{
|
||
name: 'save_memory',
|
||
description: 'Save a new memory. Defaults to workspace memory when a workspace is active.\n\n'
|
||
+ 'CRITICAL ROUTING RULES:\n'
|
||
+ '- target="workspace" (DEFAULT): ALL project data, client data, decisions, tasks, meeting notes, research findings, confidential information, names, budgets, timelines. '
|
||
+ 'Workspace memories are ISOLATED — they cannot be seen from other workspaces. Use this for ANYTHING workspace-specific.\n'
|
||
+ '- target="personal": ONLY for user preferences (favorite color, communication style), personal facts (name, role, timezone), '
|
||
+ 'and cross-workspace knowledge (general skills, tool preferences). Personal memories are shared across ALL workspaces.\n\n'
|
||
+ 'When in doubt, use workspace. Never save client names, budgets, confidential data, or project-specific information to personal memory.',
|
||
offlineCapable: true,
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {
|
||
content: { type: 'string', description: 'The memory content to save' },
|
||
kind: {
|
||
type: 'string',
|
||
enum: [...SAVE_KINDS],
|
||
description: 'What the memory is: fact (default), preference, decision, event (something that happened, with its date in the text), note.',
|
||
},
|
||
importance: {
|
||
type: 'string',
|
||
enum: ['critical', 'important', 'normal', 'temporary'],
|
||
description: 'How important is this memory',
|
||
},
|
||
target: {
|
||
type: 'string',
|
||
enum: ['workspace', 'personal'],
|
||
description: 'Which memory to save to. Workspace (default): ALL project/client/confidential data — isolated per workspace. Personal: ONLY user preferences and cross-workspace knowledge — shared across all workspaces.',
|
||
},
|
||
source: {
|
||
type: 'string',
|
||
enum: ['user_stated', 'tool_verified', 'agent_inferred'],
|
||
description: 'Provenance: user_stated = the user said this, tool_verified = confirmed via tool output, agent_inferred = your own analysis/synthesis.',
|
||
},
|
||
confidence: {
|
||
type: 'string',
|
||
enum: ['high', 'medium', 'low', 'unverified'],
|
||
description: 'Confidence level. Auto-derived from source if omitted: tool_verified→high, user_stated→medium, agent_inferred→low.',
|
||
},
|
||
},
|
||
required: ['content'],
|
||
},
|
||
execute: async (args) => {
|
||
const content = typeof args.content === 'string' ? args.content.trim() : '';
|
||
if (!content) return 'Memory save skipped: content is empty.';
|
||
|
||
// Review C1: scan LLM-controlled content for prompt-injection payloads
|
||
// BEFORE any write.
|
||
const scan = scanForInjection(content, 'user_input');
|
||
if (!scan.safe) {
|
||
return `Memory save blocked: content contains suspected prompt-injection payload (${scan.flags.join(', ')}). The content was NOT saved.`;
|
||
}
|
||
|
||
// W2.10: Rate limit memory saves to prevent flooding (50 per session)
|
||
// Review C2: counter is externally-owned so it survives tool-array rebuilds.
|
||
saveCounter.count++;
|
||
if (saveCounter.count > MAX_SAVES_PER_SESSION) {
|
||
return `Memory save rate limit reached (${MAX_SAVES_PER_SESSION} saves this session). This prevents memory flooding. Start a new session to save more memories.`;
|
||
}
|
||
|
||
// Untrusted args: validate against the canonical unions, default on mismatch.
|
||
let importance: MemoryImportance =
|
||
typeof args.importance === 'string' && (MEMORY_IMPORTANCE as readonly string[]).includes(args.importance)
|
||
? (args.importance as MemoryImportance)
|
||
: 'normal';
|
||
const kind: MemoryKind =
|
||
typeof args.kind === 'string' && (SAVE_KINDS as readonly string[]).includes(args.kind)
|
||
? (args.kind as MemoryKind)
|
||
: 'fact';
|
||
const target = typeof args.target === 'string' ? args.target : 'workspace';
|
||
const source: MemorySource =
|
||
typeof args.source === 'string' && (MEMORY_SOURCES as readonly string[]).includes(args.source)
|
||
? (args.source as MemorySource)
|
||
: 'user_stated';
|
||
const ws = activeWorkspace();
|
||
|
||
// F6: Derive confidence from source if not explicitly provided
|
||
const confidence: ConfidenceLevel = (args.confidence as ConfidenceLevel) ?? deriveConfidence(source);
|
||
|
||
// F7: Strict workspace routing — respect target parameter, with safety guardrail
|
||
let effectiveTarget = target;
|
||
|
||
// B1-guardrail: Detect workspace-specific content being routed to personal memory
|
||
// If a workspace is active and content contains confidential/project signals, redirect to workspace
|
||
if (effectiveTarget === 'personal' && ws != null) {
|
||
const workspaceSpecificPatterns = [
|
||
/\bconfidential\b/i, /\bclient\b/i, /\bbudget\b/i, /\bengagement\b/i,
|
||
/\bdeliverable\b/i, /\bmilestone\b/i, /\btimeline\b/i, /\bdeadline\b/i,
|
||
/\bceo\b/i, /\bcto\b/i, /\bcfo\b/i, /\bcoo\b/i,
|
||
/\$\d{2,}[,.]?\d*[kmb]?\b/i, // dollar amounts ($500K, $1.2M, etc.)
|
||
/\bproject\b.*\b(?:plan|status|update)\b/i,
|
||
/\bcontract\b/i, /\bproposal\b/i, /\bnda\b/i, /\bsow\b/i,
|
||
];
|
||
if (workspaceSpecificPatterns.some(p => p.test(content))) {
|
||
effectiveTarget = 'workspace';
|
||
}
|
||
}
|
||
|
||
const useWorkspace = effectiveTarget === 'workspace' && ws != null;
|
||
const targetScope = useWorkspace ? ws! : PERSONAL_SCOPE;
|
||
const otherScope = useWorkspace ? PERSONAL_SCOPE : ws;
|
||
const mindLabel = useWorkspace ? 'workspace' : 'personal';
|
||
|
||
// F22: Detect dramatic claims and flag them
|
||
const dramaticClaims = detectDramaticClaims(content);
|
||
let dramaticFlag = '';
|
||
if (dramaticClaims.length) {
|
||
// Downgrade importance to 'temporary' for dramatic claims unless explicitly set to critical
|
||
if (importance !== 'critical') {
|
||
importance = 'temporary';
|
||
}
|
||
dramaticFlag = ` [flag: dramatic_claim (${dramaticClaims.join(', ')})]`;
|
||
}
|
||
|
||
// ── Dedup (F7 cross-memory + F16 normalized) ──────────────
|
||
// Identical text in the target scope is caught by the store itself;
|
||
// this also catches normalized matches and copies in the other scope.
|
||
const normalized = normalizeForDedup(content);
|
||
const findDuplicate = async (scope: MemoryScope): Promise<string | null> => {
|
||
if (!normalized) return null;
|
||
try {
|
||
const candidates = await deps.memory.search(content, { scopes: [scope], limit: DEDUP_CANDIDATES });
|
||
const match = candidates.find(c => normalizeForDedup(c.text) === normalized);
|
||
return match ? match.id : null;
|
||
} catch {
|
||
return null; // non-blocking — proceed with save if dedup check fails
|
||
}
|
||
};
|
||
const sameScopeDuplicate = await findDuplicate(targetScope);
|
||
if (sameScopeDuplicate) {
|
||
return `Memory already exists in ${mindLabel} memory (${sameScopeDuplicate}) — skipped duplicate save.`;
|
||
}
|
||
if (otherScope) {
|
||
const crossDuplicate = await findDuplicate(otherScope);
|
||
if (crossDuplicate) {
|
||
const otherLabel = useWorkspace ? 'personal' : 'workspace';
|
||
return `Memory already exists in ${otherLabel} memory (${crossDuplicate}) — skipped cross-memory duplicate save.`;
|
||
}
|
||
}
|
||
|
||
// Skills 2.0 gap K: write-path conflict detection. Conflicts are data,
|
||
// not errors: the memory is still saved, and the response is flagged
|
||
// so the agent surfaces the conflict to the user.
|
||
let conflictFlag = '';
|
||
try {
|
||
const recent = await deps.memory.list({ scopes: [targetScope], limit: CONTRADICTION_WINDOW });
|
||
const contradiction = detectContradiction(content, recent.map(r => ({ content: r.text })));
|
||
if (contradiction.isContradiction && contradiction.conflictsWith) {
|
||
conflictFlag = ` [flag: contradicts_existing (${contradiction.conflictsWith.slice(0, 80).replace(/\s+/g, ' ').trim()}…)]`;
|
||
}
|
||
} catch { /* non-blocking — contradiction check failure proceeds with save */ }
|
||
|
||
const [change] = await deps.memory.remember({
|
||
scope: targetScope,
|
||
text: content,
|
||
kind,
|
||
importance,
|
||
source,
|
||
origin: 'agent',
|
||
metadata: { confidence },
|
||
});
|
||
if (change?.event === 'unchanged') {
|
||
return `Memory already exists in ${mindLabel} memory (${change.record.id}) — skipped duplicate save.`;
|
||
}
|
||
return `Memory saved to ${mindLabel} memory (kind: ${kind}, importance: ${importance}, source: ${source}, confidence: ${confidence}${dramaticFlag}${conflictFlag}).`;
|
||
},
|
||
},
|
||
{
|
||
name: 'add_task',
|
||
description: 'Add a task to the awareness layer for tracking',
|
||
offlineCapable: true,
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {
|
||
content: { type: 'string', description: 'Task description' },
|
||
priority: { type: 'number', description: 'Priority (0-10, higher = more important)' },
|
||
},
|
||
required: ['content'],
|
||
},
|
||
execute: async (args) => {
|
||
const taskContent = typeof args.content === 'string' ? args.content.slice(0, 2000) : '';
|
||
const item = deps.awareness.add('task', taskContent, (args.priority as number) ?? 5);
|
||
return `Task added: "${item.content}" (priority: ${item.priority})`;
|
||
},
|
||
},
|
||
];
|
||
}
|