@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/memory/providers/graphiti/GraphitiMapper.js

@@ -0,0 +1,116 @@
+import { MEMORY_TYPES, MEMORY_VERIFICATIONS } from '../../types.js';
+function isStringList(value) {
+    return Array.isArray(value) && value.every(item => typeof item === 'string');
+}
+function isStringMap(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        && Object.values(value).every(item => typeof item === 'string');
+}
+function isValidProvenance(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const provenance = value;
+    for (const key of ['taskId', 'commitSha', 'branch', 'workspaceId']) {
+        if (provenance[key] !== undefined && typeof provenance[key] !== 'string')
+            return false;
+    }
+    for (const key of ['files', 'tests']) {
+        if (provenance[key] !== undefined && !isStringList(provenance[key]))
+            return false;
+    }
+    if (provenance.worktreeHashes !== undefined && !isStringMap(provenance.worktreeHashes))
+        return false;
+    return true;
+}
+export function parseEpisodeMeta(sourceDescription) {
+    if (!sourceDescription)
+        return undefined;
+    try {
+        const value = JSON.parse(sourceDescription);
+        if (!value || value.andorra !== 1 || typeof value.title !== 'string'
+            || !MEMORY_TYPES.includes(value.type))
+            return undefined;
+        if (value.verification !== undefined && !MEMORY_VERIFICATIONS.includes(value.verification))
+            return undefined;
+        if (value.confidence !== undefined && typeof value.confidence !== 'number')
+            return undefined;
+        if (value.entities !== undefined && !isStringList(value.entities))
+            return undefined;
+        if (value.provenance !== undefined && !isValidProvenance(value.provenance))
+            return undefined;
+        return value;
+    }
+    catch { /* Foreign episode: no Andorra metadata. */ }
+    return undefined;
+}
+function episodeBody(event) {
+    const lines = [event.title, event.content];
+    if (event.supersedes)
+        lines.push(`This fact supersedes and replaces the earlier fact: "${event.supersedes}". The earlier fact is historical only and no longer current.`);
+    if (event.source?.tests?.length)
+        lines.push(`Verified by: ${event.source.tests.join(', ')}.`);
+    if (event.entities?.length)
+        lines.push(`Related components: ${event.entities.join(', ')}.`);
+    return lines.join('\n');
+}
+export function eventToMessage(event, id) {
+    const meta = {
+        andorra: 1,
+        type: event.type,
+        title: event.title,
+        verification: event.verification,
+        ...(event.confidence !== undefined ? { confidence: event.confidence } : {}),
+        ...(event.entities?.length ? { entities: event.entities } : {}),
+        ...(event.source ? { provenance: event.source } : {}),
+    };
+    return {
+        uuid: id,
+        name: `andorra:${event.type}`,
+        role: 'andorra-memory',
+        role_type: 'system',
+        content: episodeBody(event),
+        timestamp: event.createdAt,
+        source_description: JSON.stringify(meta),
+    };
+}
+function timestamp(value) {
+    if (!value)
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+export function factToResult(fact, metaByEpisode, score) {
+    const meta = fact.episodes.map(id => metaByEpisode.get(id)).find(Boolean);
+    const now = Date.now();
+    const validAt = timestamp(fact.valid_at);
+    const invalidAt = timestamp(fact.invalid_at);
+    const expiredAt = timestamp(fact.expired_at);
+    const notYetValid = validAt !== undefined && validAt > now;
+    const ended = (invalidAt !== undefined && invalidAt <= now) || (expiredAt !== undefined && expiredAt <= now);
+    const provenance = meta?.provenance;
+    return {
+        id: fact.uuid,
+        type: (meta?.type ?? 'historical_fact'),
+        title: meta?.title ?? fact.fact.slice(0, 120),
+        // Graphiti fact text is model-derived and may paraphrase the source
+        // episode. Prefer the original episode body for stable duplicate checks.
+        content: meta?.episodeContent ?? fact.fact,
+        temporalStatus: notYetValid || ended ? 'historical' : 'current',
+        validFrom: fact.valid_at ?? fact.created_at,
+        validUntil: fact.invalid_at ?? fact.expired_at ?? undefined,
+        verification: meta?.verification ?? 'unverified',
+        ...(meta?.confidence !== undefined ? { confidence: meta.confidence } : {}),
+        ...(meta?.entities?.length ? { entities: meta.entities } : {}),
+        ...(provenance ? { provenance } : {}),
+        ...(score !== undefined ? { score } : {}),
+    };
+}
+export function episodeMetas(episodes) {
+    const map = new Map();
+    for (const episode of episodes) {
+        const meta = parseEpisodeMeta(episode.source_description);
+        if (meta)
+            map.set(episode.uuid, { ...meta, episodeContent: episode.content });
+    }
+    return map;
+}

package/dist/src/memory/providers/graphiti/GraphitiMemoryProvider.d.ts

@@ -0,0 +1,27 @@
+import type { MemoryProvider } from '../../MemoryProvider.js';
+import type { MemoryEvent, MemoryHealth, MemoryInvalidation, MemoryQuery, MemoryResult, MemoryScope, MemoryWriteResult } from '../../types.js';
+import { GraphitiClient } from './GraphitiClient.js';
+export declare class GraphitiMemoryProvider implements MemoryProvider {
+    private readonly client;
+    private static readonly EPISODE_WINDOWS;
+    private groupId;
+    private metaByEpisode;
+    private readonly resolvedEpisodeIds;
+    private episodeWindow;
+    /** Fact UUIDs observed through this provider's scoped searches. */
+    private readonly ownedFactIds;
+    constructor(client: GraphitiClient);
+    initialize(scope: MemoryScope): Promise<void>;
+    private requireScope;
+    private refreshMetadata;
+    search(query: MemoryQuery): Promise<MemoryResult[]>;
+    getHistory(query: MemoryQuery): Promise<MemoryResult[]>;
+    private withMetadata;
+    private groupIdRepositoryId;
+    remember(event: MemoryEvent, options?: {
+        signal?: AbortSignal;
+    }): Promise<MemoryWriteResult>;
+    invalidate(filter: MemoryInvalidation): Promise<void>;
+    deleteScope(scope: MemoryScope): Promise<void>;
+    health(): Promise<MemoryHealth>;
+}

package/dist/src/memory/providers/graphiti/GraphitiMemoryProvider.js

@@ -0,0 +1,137 @@
+import { randomUUID } from 'node:crypto';
+import { memoryGroupId } from '../../repository.js';
+import { MEMORY_DEFAULTS } from '../../types.js';
+import { GraphitiUnavailableError } from './GraphitiClient.js';
+import { episodeMetas, eventToMessage, factToResult } from './GraphitiMapper.js';
+export class GraphitiMemoryProvider {
+    client;
+    static EPISODE_WINDOWS = [200, 1000, 5000];
+    groupId = '';
+    metaByEpisode = new Map();
+    resolvedEpisodeIds = new Set();
+    episodeWindow = GraphitiMemoryProvider.EPISODE_WINDOWS[0];
+    /** Fact UUIDs observed through this provider's scoped searches. */
+    ownedFactIds = new Set();
+    constructor(client) {
+        this.client = client;
+    }
+    async initialize(scope) {
+        if (!scope.repositoryId)
+            throw new Error('A repository scope is required for persistent memory');
+        this.groupId = memoryGroupId(scope.repositoryId);
+        this.ownedFactIds.clear();
+        this.resolvedEpisodeIds.clear();
+        await this.refreshMetadata();
+    }
+    requireScope() {
+        if (!this.groupId)
+            throw new Error('GraphitiMemoryProvider.initialize() must complete before use');
+        return this.groupId;
+    }
+    async refreshMetadata(signal) {
+        const episodes = await this.client.listEpisodes(this.requireScope(), this.episodeWindow, signal);
+        this.metaByEpisode = episodeMetas(episodes);
+        for (const episode of episodes)
+            this.resolvedEpisodeIds.add(episode.uuid);
+    }
+    async search(query) {
+        const groupId = this.requireScope();
+        if (query.repositoryId && query.repositoryId !== this.groupIdRepositoryId(groupId)) {
+            throw new Error(`Memory query repository ${query.repositoryId} does not match the initialized scope`);
+        }
+        const limit = query.limit ?? MEMORY_DEFAULTS.maxRetrievedMemories;
+        let facts = await this.client.searchFacts({ group_ids: [groupId], query: query.query, max_facts: Math.min(Math.max(limit * 2, 10), 50) }, query.signal);
+        facts = await this.withMetadata(facts, query.signal);
+        for (const fact of facts)
+            this.ownedFactIds.add(fact.uuid);
+        const results = facts.map((fact, index) => factToResult(fact, this.metaByEpisode, 1 / (index + 1)));
+        const filtered = query.includeHistorical ? results : results.filter(result => result.temporalStatus === 'current');
+        return filtered.slice(0, limit);
+    }
+    async getHistory(query) {
+        return this.search({ ...query, includeHistorical: true });
+    }
+    async withMetadata(facts, signal) {
+        const windows = GraphitiMemoryProvider.EPISODE_WINDOWS;
+        let refreshedAtMax = false;
+        while (facts.some(fact => fact.episodes.some(id => !this.resolvedEpisodeIds.has(id)))) {
+            const next = windows[windows.indexOf(this.episodeWindow) + 1];
+            if (next === undefined) {
+                if (refreshedAtMax)
+                    break;
+                refreshedAtMax = true;
+                try {
+                    await this.refreshMetadata(signal);
+                }
+                catch {
+                    break;
+                }
+                continue;
+            }
+            this.episodeWindow = next;
+            try {
+                await this.refreshMetadata(signal);
+            }
+            catch {
+                break;
+            }
+        }
+        return facts;
+    }
+    groupIdRepositoryId(groupId) {
+        return groupId.replace(/^repo:/, '');
+    }
+    async remember(event, options) {
+        const groupId = this.requireScope();
+        if (event.repositoryId !== this.groupIdRepositoryId(groupId)) {
+            throw new Error(`Memory event repository ${event.repositoryId} does not match the initialized scope`);
+        }
+        const id = event.id ?? randomUUID();
+        const message = eventToMessage(event, id);
+        await this.client.addEpisode({ group_id: groupId, messages: [message] }, options?.signal);
+        this.metaByEpisode.set(id, {
+            andorra: 1, type: event.type, title: event.title, verification: event.verification,
+            ...(event.confidence !== undefined ? { confidence: event.confidence } : {}),
+            ...(event.entities?.length ? { entities: event.entities } : {}),
+            ...(event.source ? { provenance: event.source } : {}),
+            episodeContent: message.content,
+        });
+        this.resolvedEpisodeIds.add(id);
+        return { id, persisted: true };
+    }
+    async invalidate(filter) {
+        const groupId = this.requireScope();
+        if (filter.repositoryId !== this.groupIdRepositoryId(groupId)) {
+            throw new Error(`Memory invalidation repository ${filter.repositoryId} does not match the initialized scope`);
+        }
+        for (const id of filter.ids ?? []) {
+            if (!this.ownedFactIds.has(id))
+                throw new Error(`Memory edge ${id} is not owned by the initialized repository scope`);
+            await this.client.deleteEntityEdge(id);
+            this.ownedFactIds.delete(id);
+        }
+    }
+    async deleteScope(scope) {
+        const groupId = this.requireScope();
+        if (scope.repositoryId !== this.groupIdRepositoryId(groupId)) {
+            throw new Error(`Memory deletion repository ${scope.repositoryId} does not match the initialized scope`);
+        }
+        await this.client.deleteGroup(groupId);
+        this.metaByEpisode.clear();
+        this.resolvedEpisodeIds.clear();
+        this.ownedFactIds.clear();
+    }
+    async health() {
+        try {
+            return await this.client.health()
+                ? { status: 'ok' }
+                : { status: 'unavailable', detail: 'Graphiti service did not answer the health check' };
+        }
+        catch (error) {
+            return {
+                status: 'unavailable',
+                detail: error instanceof GraphitiUnavailableError ? error.message : 'Graphiti service is unreachable',
+            };
+        }
+    }
+}

package/dist/src/memory/providers/graphiti/GraphitiTypes.d.ts

@@ -0,0 +1,57 @@
+/** Wire types for the Graphiti REST service (getzep/graphiti server). */
+export interface GraphitiMessage {
+    uuid: string;
+    name: string;
+    role: string;
+    role_type: 'system';
+    content: string;
+    timestamp: string;
+    /** Carries the Andorra metadata JSON for the episode. */
+    source_description: string;
+}
+export interface GraphitiAddMessagesRequest {
+    group_id: string;
+    messages: GraphitiMessage[];
+}
+export interface GraphitiSearchQuery {
+    group_ids: string[];
+    query: string;
+    max_facts: number;
+}
+export interface GraphitiFactResult {
+    uuid: string;
+    name: string;
+    fact: string;
+    valid_at: string | null;
+    invalid_at: string | null;
+    created_at: string;
+    expired_at: string | null;
+    source_node_uuid: string;
+    target_node_uuid: string;
+    episodes: string[];
+}
+export interface GraphitiSearchResults {
+    facts: GraphitiFactResult[];
+}
+export interface GraphitiEpisodeNode {
+    uuid: string;
+    name: string;
+    group_id: string;
+    content: string;
+    source: string;
+    source_description: string;
+    created_at: string;
+    valid_at: string;
+}
+/** Metadata stored on every Andorra episode in source_description. */
+export interface GraphitiEpisodeMeta {
+    andorra: 1;
+    type: string;
+    title: string;
+    verification: string;
+    confidence?: number;
+    entities?: string[];
+    provenance?: Record<string, unknown>;
+    /** Internal cache field populated from the source episode, never serialized. */
+    episodeContent?: string;
+}

package/dist/src/memory/providers/graphiti/GraphitiTypes.js

@@ -0,0 +1,2 @@
+/** Wire types for the Graphiti REST service (getzep/graphiti server). */
+export {};

package/dist/src/memory/redaction.d.ts

@@ -0,0 +1,11 @@
+export declare function containsSecret(text: string): boolean;
+export declare function redactSecrets(text: string): {
+    text: string;
+    redactions: number;
+};
+/**
+ * Screen a list of provenance/entity strings (test commands, file paths,
+ * component names) before persistence. Each value is redacted span-wise;
+ * values that were dominated by credential material are dropped entirely.
+ */
+export declare function redactStringList(values: string[], limit: number): string[];

package/dist/src/memory/redaction.js

@@ -0,0 +1,58 @@
+/**
+ * Secret screening for persistent memory. Candidates are redacted span-wise;
+ * a candidate dominated by secrets is rejected by the policy layer. This is a
+ * belt-and-braces filter, not a vault: memory content must never include
+ * credentials in the first place.
+ */
+const PATTERNS = [
+    /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g,
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b/g,
+    /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+    /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/g,
+    /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+    /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g,
+    /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi,
+    /\b[a-z][a-z0-9+.-]*:\/\/[^\s/@:]*:[^\s/@]+@/gi,
+    /["']?(?:api[_-]?key|password|passwd|secret|client[_-]?secret|access[_-]?token|refresh[_-]?token|private[_-]?key|auth[_-]?token|database[_-]?url|redis[_-]?url|postgres(?:ql)?[_-]?url|mysql[_-]?url|mongodb?[_-]?url)["']?\s*[:=]\s*(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,}]+)/gi,
+];
+export function containsSecret(text) {
+    return PATTERNS.some(pattern => {
+        pattern.lastIndex = 0;
+        return pattern.test(text);
+    });
+}
+export function redactSecrets(text) {
+    let redactions = 0;
+    let result = text;
+    for (const pattern of PATTERNS) {
+        pattern.lastIndex = 0;
+        result = result.replace(pattern, match => {
+            redactions++;
+            const assignment = match.match(/^(.{0,80}?[:=]\s*)/);
+            return assignment && match.length <= 500 ? `${assignment[1]}[REDACTED]` : '[REDACTED]';
+        });
+    }
+    return { text: result, redactions };
+}
+/**
+ * Screen a list of provenance/entity strings (test commands, file paths,
+ * component names) before persistence. Each value is redacted span-wise;
+ * values that were dominated by credential material are dropped entirely.
+ */
+export function redactStringList(values, limit) {
+    const cleaned = [];
+    for (const value of values) {
+        if (typeof value !== 'string')
+            continue;
+        const { text, redactions } = redactSecrets(value.trim());
+        if (!text)
+            continue;
+        if (redactions > 0 && text.replace(/\[REDACTED\]/g, '').trim().length < 12)
+            continue;
+        cleaned.push(text.slice(0, 300));
+        if (cleaned.length >= limit)
+            break;
+    }
+    return cleaned;
+}

package/dist/src/memory/repository.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Stable repository identity for memory isolation. The readable slug is
+ * intentionally lossy; the hash of the canonical remote is the collision
+ * boundary. Relative filesystem remotes are first resolved against the repo.
+ */
+export declare function deriveRepositoryId(remoteUrl?: string, rootPath?: string): string;
+/** Graphiti group id; the only scope the provider ever searches. */
+export declare function memoryGroupId(repositoryId: string): string;
+type GitRunner = (args: string[], cwd: string) => Promise<string>;
+export declare function resolveRepositoryId(workspace: string, run?: GitRunner): Promise<string>;
+export {};

package/dist/src/memory/repository.js

@@ -0,0 +1,74 @@
+import { createHash } from 'node:crypto';
+import { workspaceGitMetadata } from '../workspace-git-metadata.js';
+import { isAbsolute, resolve } from 'node:path';
+function canonicalRemote(remoteUrl, rootPath) {
+    const trimmed = remoteUrl.trim().replace(/\/+$/, '').replace(/\.git$/i, '');
+    const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed);
+    const scp = /^(?:[^@]+@)?([^:/]+):(.+)$/.exec(trimmed);
+    if (!hasScheme && !scp && !isAbsolute(trimmed)) {
+        const absolute = resolve(rootPath || '.', trimmed).replace(/\\/g, '/');
+        return `file:${absolute}`;
+    }
+    try {
+        const url = new URL(trimmed);
+        const host = url.hostname.toLowerCase();
+        const port = url.port ? `/${url.port}` : '';
+        const path = ['github.com', 'gitlab.com'].includes(host) ? url.pathname.toLowerCase() : url.pathname;
+        // Preserve the pre-existing network-remote identity shape (host/path, no
+        // scheme) so this fix does not fork existing Graphiti groups. File/self-
+        // hosted paths remain case-sensitive where the transport can be.
+        return `${host}${port}${path}`;
+    }
+    catch {
+        if (scp) {
+            const host = scp[1].toLowerCase();
+            const path = ['github.com', 'gitlab.com'].includes(host) ? scp[2].toLowerCase() : scp[2];
+            return `${host}/${path}`;
+        }
+        if (isAbsolute(trimmed))
+            return `file:${trimmed.replace(/\\/g, '/')}`;
+        const withoutUser = trimmed.replace(/^[^/@]+@/, '');
+        const slash = withoutUser.indexOf('/');
+        if (slash < 0)
+            return withoutUser.toLowerCase();
+        return `${withoutUser.slice(0, slash).toLowerCase()}${withoutUser.slice(slash)}`;
+    }
+}
+/**
+ * Stable repository identity for memory isolation. The readable slug is
+ * intentionally lossy; the hash of the canonical remote is the collision
+ * boundary. Relative filesystem remotes are first resolved against the repo.
+ */
+export function deriveRepositoryId(remoteUrl, rootPath) {
+    if (remoteUrl?.trim()) {
+        const canonical = canonicalRemote(remoteUrl, rootPath);
+        const slug = canonical.toLowerCase()
+            .replace(/[^a-z0-9.]+/g, '-')
+            .replace(/^-+|-+$/g, '');
+        if (slug)
+            return `${slug}-${createHash('sha256').update(canonical).digest('hex').slice(0, 8)}`;
+    }
+    let root = (rootPath ?? '').replace(/\\/g, '/').replace(/\/+$/, '');
+    // Windows path identity is case-insensitive; POSIX paths are not.
+    if (/^[A-Za-z]:\//.test(root))
+        root = root.toLowerCase();
+    return `local-${createHash('sha256').update(root || 'unknown').digest('hex').slice(0, 12)}`;
+}
+/** Graphiti group id; the only scope the provider ever searches. */
+export function memoryGroupId(repositoryId) {
+    return `repo:${repositoryId}`;
+}
+const defaultRunner = workspaceGitMetadata;
+export async function resolveRepositoryId(workspace, run = defaultRunner) {
+    let remote;
+    let root;
+    try {
+        remote = (await run(['config', '--get', 'remote.origin.url'], workspace)).trim() || undefined;
+    }
+    catch { /* no remote */ }
+    try {
+        root = (await run(['rev-parse', '--show-toplevel'], workspace)).trim() || undefined;
+    }
+    catch { /* not a git worktree */ }
+    return deriveRepositoryId(remote, root ?? workspace);
+}

package/dist/src/memory/tools/memorySearchTool.d.ts

@@ -0,0 +1,4 @@
+import type { Tool } from '../../types.js';
+import type { MemoryManager } from '../MemoryManager.js';
+export declare function projectMemorySearchEventOutput(output: string): string;
+export declare function memorySearchTool(manager: MemoryManager, runId?: string): Tool;

package/dist/src/memory/tools/memorySearchTool.js

@@ -0,0 +1,77 @@
+function format(result) {
+    return {
+        id: result.id,
+        type: result.type,
+        temporalStatus: result.temporalStatus,
+        title: result.title.slice(0, 240),
+        content: result.content.slice(0, 1200),
+        verification: result.verification,
+        ...(result.validUntil ? { validUntil: result.validUntil } : {}),
+        ...(result.requiresRevalidation ? { requiresRevalidation: true } : {}),
+        ...(result.entities?.length ? { entities: result.entities.slice(0, 5).map(value => value.slice(0, 160)) } : {}),
+        ...(result.provenance?.commitSha ? { commit: result.provenance.commitSha.slice(0, 7) } : {}),
+        ...(result.provenance?.tests?.length ? { tests: result.provenance.tests.slice(0, 3).map(value => value.slice(0, 240)) } : {}),
+    };
+}
+export function projectMemorySearchEventOutput(output) {
+    try {
+        const parsed = JSON.parse(output);
+        if (!Array.isArray(parsed))
+            return output;
+        return JSON.stringify(parsed.map(item => {
+            if (!item || typeof item !== 'object')
+                return item;
+            const { content: _omitted, ...metadata } = item;
+            return metadata;
+        }));
+    }
+    catch {
+        return output;
+    }
+}
+function serializeResults(results) {
+    let formatted = results.map(format);
+    let output = JSON.stringify(formatted, null, 1);
+    if (output.length > 20_000) {
+        formatted = formatted.map(item => ({ ...item, content: item.content.slice(0, 500) }));
+        output = JSON.stringify(formatted, null, 1);
+    }
+    if (output.length > 20_000)
+        output = JSON.stringify(formatted.slice(0, 10), null, 1);
+    return output;
+}
+export function memorySearchTool(manager, runId) {
+    return {
+        name: 'memory_search',
+        description: 'Search persistent project memory: past architecture decisions and their reasons, verified bug fixes, conventions, procedures and lessons from previous tasks. Persistent memory requires Full Access workspace permissions. Returns currently-valid facts by default; set includeHistorical for superseded facts. Memories are advisory; current repository state is authoritative.',
+        parameters: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'What to remember, e.g. "why did sessions move from Redis to PostgreSQL"' },
+                includeHistorical: { type: 'boolean', description: 'Include superseded/historical facts (default false)' },
+                limit: { type: 'integer', minimum: 1, maximum: 20, description: 'Maximum results (default 10)' },
+            },
+            required: ['query'],
+            additionalProperties: false,
+        },
+        execute: async (args, context) => {
+            context.signal.throwIfAborted();
+            if (typeof args.query !== 'string' || !args.query.trim() || args.query.length > 2000)
+                throw new Error('Provide a query string of 1-2000 characters');
+            if (args.limit !== undefined && (typeof args.limit !== 'number' || !Number.isInteger(args.limit) || args.limit < 1 || args.limit > 20))
+                throw new Error('limit must be an integer from 1 to 20');
+            if (!manager.activeFor(runId))
+                return 'Persistent memory is unavailable for this run (workspace permissions, not configured or service down); nothing was searched.';
+            const results = await manager.searchMemories(args.query, {
+                includeHistorical: args.includeHistorical === true,
+                limit: typeof args.limit === 'number' ? args.limit : undefined,
+                signal: context.signal,
+                runId,
+            });
+            if (!results.length)
+                return 'No matching memories for this repository.';
+            return serializeResults(results);
+        },
+        eventOutput: projectMemorySearchEventOutput,
+    };
+}