@exaudeus/memory-mcp 0.1.0

package/dist/normalize.d.ts

@@ -0,0 +1,2 @@
+/** Normalize args before Zod validation: resolve aliases, default workspace, fix wildcards */
+export declare function normalizeArgs(toolName: string, raw: Record<string, unknown> | undefined, lobeNames: readonly string[]): Record<string, unknown>;

package/dist/normalize.js

@@ -0,0 +1,69 @@
+// Argument normalization for MCP tool calls.
+//
+// Agents frequently guess wrong param names. This module resolves common aliases
+// and applies defaults to avoid wasted round-trips from validation errors.
+// Pure functions — no side effects, no state.
+/** Canonical param name aliases — maps guessed names to their correct form */
+const PARAM_ALIASES = {
+    // memory_store aliases
+    key: 'title',
+    name: 'title',
+    value: 'content',
+    body: 'content',
+    text: 'content',
+    refs: 'references',
+    // memory_query aliases
+    query: 'filter',
+    search: 'filter',
+    keyword: 'filter',
+    // memory_context aliases
+    description: 'context',
+    task: 'context',
+    // lobe aliases
+    workspace: 'lobe',
+    repo: 'lobe',
+};
+/** Wildcard scope aliases — agents guess many variations instead of "*" */
+const SCOPE_WILDCARDS = new Set([
+    'all', 'everything', 'any', '*', 'global', 'project', 'repo',
+    'workspace', 'every', 'full', 'complete',
+]);
+/** Normalize args before Zod validation: resolve aliases, default workspace, fix wildcards */
+export function normalizeArgs(toolName, raw, lobeNames) {
+    const args = { ...(raw ?? {}) };
+    // 1. Resolve param aliases (move aliased keys to canonical names)
+    for (const [alias, canonical] of Object.entries(PARAM_ALIASES)) {
+        if (alias in args && !(canonical in args)) {
+            args[canonical] = args[alias];
+            delete args[alias];
+        }
+    }
+    // 2. For memory_store: accept "scope" as alias for "topic"
+    if (toolName === 'memory_store' && 'scope' in args && !('topic' in args)) {
+        args['topic'] = args['scope'];
+        delete args['scope'];
+    }
+    // 3. Default lobe to the only available one when omitted
+    if (!('lobe' in args) || args['lobe'] === undefined || args['lobe'] === '') {
+        if (lobeNames.length === 1) {
+            args['lobe'] = lobeNames[0];
+        }
+    }
+    // 4. Normalize wildcard scope values
+    if ('scope' in args && typeof args['scope'] === 'string') {
+        if (SCOPE_WILDCARDS.has(args['scope'].toLowerCase())) {
+            args['scope'] = '*';
+        }
+    }
+    // 5. For memory_query: default scope to "*" when missing
+    if (toolName === 'memory_query' && !('scope' in args)) {
+        args['scope'] = '*';
+    }
+    // 6. Normalize branch wildcard values
+    if ('branch' in args && typeof args['branch'] === 'string') {
+        if (SCOPE_WILDCARDS.has(args['branch'].toLowerCase())) {
+            args['branch'] = '*';
+        }
+    }
+    return args;
+}

package/dist/store.d.ts

@@ -0,0 +1,84 @@
+import type { MemoryEntry, TopicScope, TrustLevel, DetailLevel, QueryResult, StoreResult, CorrectResult, MemoryStats, BriefingResult, ConflictPair, MemoryConfig } from './types.js';
+export declare class MarkdownMemoryStore {
+    private readonly config;
+    private readonly memoryPath;
+    private readonly clock;
+    private readonly git;
+    private entries;
+    private corruptFileCount;
+    constructor(config: MemoryConfig);
+    /** Resolved behavior thresholds — user config merged over defaults.
+     *  Centralizes threshold resolution so every caller gets the same value. */
+    private get behavior();
+    /** Initialize the store: create memory dir and load existing entries */
+    init(): Promise<void>;
+    /** Store a new knowledge entry */
+    store(topic: TopicScope, title: string, content: string, sources?: string[], trust?: TrustLevel, references?: string[]): Promise<StoreResult>;
+    /** Query knowledge by scope and detail level */
+    query(scope: string, detail?: DetailLevel, filter?: string, branchFilter?: string): Promise<QueryResult>;
+    /** Generate a session-start briefing */
+    briefing(maxTokens?: number): Promise<BriefingResult>;
+    /** Correct an existing entry */
+    correct(id: string, correction: string, action: 'append' | 'replace' | 'delete'): Promise<CorrectResult>;
+    /** Get memory health statistics */
+    stats(): Promise<MemoryStats>;
+    /** Bootstrap: scan repo structure and seed initial knowledge */
+    bootstrap(): Promise<StoreResult[]>;
+    /** Search across all topics using keyword matching with topic-based boosting.
+     *  @param minMatch Minimum ratio of context keywords that must match (0-1, default 0.2) */
+    contextSearch(context: string, maxResults?: number, branchFilter?: string, minMatch?: number): Promise<Array<{
+        entry: MemoryEntry;
+        score: number;
+        matchedKeywords: string[];
+    }>>;
+    /** Generate a collision-resistant ID: {prefix}-{8 random hex chars} */
+    private generateId;
+    /** Compute relative file path for an entry within the memory directory */
+    private entryToRelativePath;
+    /** Sanitize git branch name for use as a directory name */
+    private sanitizeBranchName;
+    /** Get the current git branch name — delegates to injected GitService */
+    getCurrentBranch(): Promise<string>;
+    /** Write a single entry to its own file */
+    private persistEntry;
+    /** Delete the file for an entry */
+    private deleteEntryFile;
+    /** Load all entries from disk and return as an immutable snapshot.
+     *  Pure read — no mutation. Callers decide whether to cache.
+     *  Tracks corrupt files for observability without failing the load. */
+    private loadSnapshot;
+    /** Reload entries from disk into the store's working state.
+     *  This is the single mutation point for disk reads. */
+    private reloadFromDisk;
+    /** Recursively find all .md files in a directory */
+    private findMarkdownFiles;
+    /** Parse a single-entry Markdown file (# heading format).
+     *  Validates topic and trust at the boundary — rejects corrupt files. */
+    private parseSingleEntry;
+    private formatEntry;
+    private isFresh;
+    /** Days elapsed since entry was last accessed */
+    private daysSinceAccess;
+    private summarize;
+    /** Get HEAD SHA for source tracking — delegates to injected GitService */
+    private getGitSha;
+    /** Get total storage size in bytes, or null if unmeasurable */
+    private getStorageSize;
+    private formatBytes;
+    /** Find entries in the same topic with significant overlap (dedup detection).
+     *  Uses hybrid jaccard+containment similarity. */
+    private findRelatedEntries;
+    /** Fetch raw MemoryEntry objects by ID for conflict detection.
+     *  Must be called after query() (which calls reloadFromDisk) to ensure entries are current. */
+    getEntriesByIds(ids: readonly string[]): MemoryEntry[];
+    /** Detect potential conflicts in a result set — lazy, high-signal, never background.
+     *  Compares all pairs from the given entries using similarity().
+     *  Only flags pairs where both entries have substantive content (>50 chars) and
+     *  similarity exceeds 0.6. Returns at most 2 pairs to avoid overwhelming the agent.
+     *
+     *  Accepts a minimal shape so it works with both MemoryEntry and QueryEntry (full detail). */
+    detectConflicts(entries: readonly Pick<MemoryEntry, 'id' | 'title' | 'content' | 'confidence' | 'created' | 'topic' | 'trust'>[]): ConflictPair[];
+    /** Find preferences relevant to a given entry (cross-topic overlap).
+     *  Lower threshold than dedup since preferences are always worth surfacing. */
+    private findRelevantPreferences;
+}