@tonycasey/lisa 0.5.13

package/dist/templates/agents/skills/memory/scripts/memory.js

@@ -0,0 +1,533 @@
+#!/usr/bin/env node
+"use strict";
+// Lightweight Graphiti memory helper usable by any model.
+// Commands:
+//   node memory.js add "text to remember" [--group <id>] [--tag foo] [--type <type>] [--source <src>] [--cache]
+//   node memory.js load [--group <id>] [--query <q>] [--limit N] [--cache]
+// Options:
+//   --endpoint <url> : MCP endpoint (default env GRAPHITI_ENDPOINT or http://localhost:8010/mcp/)
+//   --type <type>    : Entity type (decision, pattern, bug, etc.) - maps to tag
+//   --cache          : write successful responses to cache/memory.log and use it as fallback on errors.
+// Modes:
+//   local        : Local Docker MCP server (default)
+//   zep-cloud    : Zep Cloud native REST API (no Docker required)
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+// ============================================================================
+// Group ID Utilities (inline to avoid import complexity in deployed skills)
+// ============================================================================
+const MAX_GROUP_ID_LENGTH = 128;
+/**
+ * Normalize a path to a valid group ID string.
+ * Works cross-platform (Windows and Unix).
+ * /Users/tony.casey/Repos/api -> users-tony_casey-repos-api
+ * C:\dev\lisa -> c-dev-lisa
+ */
+function normalizePathToGroupId(absolutePath) {
+    let normalized = absolutePath
+        .toLowerCase()
+        .replace(/^[a-z]:/i, (match) => match.charAt(0)) // C: -> c
+        .replace(/^\//, '') // Remove leading slash (Unix)
+        .replace(/\\/g, '-') // Backslash to dash (Windows)
+        .replace(/\//g, '-') // Forward slash to dash (Unix)
+        .replace(/\./g, '_') // Dots to underscores
+        .replace(/^-+/, '') // Remove leading dashes
+        .replace(/-+/g, '-'); // Collapse multiple dashes
+    if (normalized.length > MAX_GROUP_ID_LENGTH) {
+        normalized = normalized.slice(-MAX_GROUP_ID_LENGTH);
+    }
+    return normalized;
+}
+/**
+ * Get the current folder's group ID.
+ */
+function getCurrentGroupId(cwd = process.cwd()) {
+    return normalizePathToGroupId(cwd);
+}
+/**
+ * Check if we're on Windows
+ */
+function isWindows() {
+    return os.platform() === 'win32';
+}
+/**
+ * Get the root boundary for hierarchical traversal.
+ * - Windows: drive root (e.g., C:\) or home directory, whichever is deeper
+ * - Unix: home directory or /
+ */
+function getRootBoundary(cwd = process.cwd()) {
+    const homeDir = os.homedir();
+    if (isWindows()) {
+        // On Windows, check if cwd is under home directory
+        const cwdLower = cwd.toLowerCase();
+        const homeLower = homeDir.toLowerCase();
+        if (cwdLower.startsWith(homeLower)) {
+            return homeDir; // Under home, use home as boundary
+        }
+        // Not under home (e.g., C:\dev\), use drive root as boundary
+        const driveRoot = path.parse(cwd).root; // e.g., "C:\"
+        return driveRoot;
+    }
+    // Unix: use home directory if under it, otherwise use /
+    if (cwd.startsWith(homeDir)) {
+        return homeDir;
+    }
+    return '/';
+}
+/**
+ * Get hierarchical group IDs from current folder up to root boundary.
+ * Returns array ordered from most specific (current) to least specific (root).
+ * Works cross-platform (Windows and Unix).
+ */
+function getHierarchicalGroupIds(cwd = process.cwd()) {
+    const rootBoundary = getRootBoundary(cwd);
+    const groups = [];
+    let currentPath = path.resolve(cwd);
+    const maxDepth = 10; // Safety limit
+    let depth = 0;
+    while (depth < maxDepth) {
+        groups.push(normalizePathToGroupId(currentPath));
+        // Stop if we've reached the root boundary
+        if (currentPath.toLowerCase() === rootBoundary.toLowerCase()) {
+            break;
+        }
+        const parentPath = path.dirname(currentPath);
+        // Stop if we can't go up anymore (reached filesystem root)
+        if (parentPath === currentPath) {
+            break;
+        }
+        currentPath = parentPath;
+        depth++;
+    }
+    return groups;
+}
+// ============================================================================
+// Zep Cloud Native API Client (for zep-cloud mode)
+// ============================================================================
+const ZEP_BASE_URL = 'https://api.getzep.com/api/v2';
+async function zepFetch(apiKey, urlPath, options = {}, timeoutMs = 15000) {
+    const url = `${ZEP_BASE_URL}${urlPath}`;
+    const resp = await fetch(url, {
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Api-Key ${apiKey}`,
+            ...(options.headers || {}),
+        },
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    const text = await resp.text();
+    let data;
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch (_err) {
+        throw new Error(`Invalid JSON from Zep (${resp.status}): ${text.slice(0, 200)}`);
+    }
+    if (!resp.ok) {
+        // Zep returns errors in 'message' field, not 'error.message'
+        const errorMsg = data.message ||
+            data.error?.message ||
+            data.error?.detail ||
+            `HTTP ${resp.status}`;
+        throw new Error(errorMsg);
+    }
+    return data;
+}
+/**
+ * Zep v3 uses a thread-based approach:
+ * 1. Ensure user exists
+ * 2. Get or create a thread for the project
+ * 3. Add messages to the thread
+ * Zep extracts facts automatically from messages
+ */
+async function zepEnsureUser(apiKey, userId) {
+    try {
+        // Try to create user - will fail if exists, which is fine
+        await zepFetch(apiKey, '/users', {
+            method: 'POST',
+            body: JSON.stringify({
+                user_id: userId,
+                first_name: 'Lisa',
+                last_name: 'Memory',
+            }),
+        });
+    }
+    catch (err) {
+        // User already exists is ok (400 with "user already exists")
+        if (!(err instanceof Error && err.message.includes('already exists'))) {
+            throw err;
+        }
+    }
+    return { user_id: userId };
+}
+async function zepGetOrCreateThread(apiKey, threadId, userId) {
+    try {
+        // Try to create thread - will fail if exists
+        await zepFetch(apiKey, '/threads', {
+            method: 'POST',
+            body: JSON.stringify({
+                thread_id: threadId,
+                user_id: userId,
+                metadata: { project: threadId, created_by: 'lisa' },
+            }),
+        });
+    }
+    catch (err) {
+        // Thread already exists is ok
+        if (!(err instanceof Error && err.message.includes('already exists'))) {
+            throw err;
+        }
+    }
+    return { thread_id: threadId };
+}
+async function zepAddMemory(apiKey, text, groupId, source) {
+    // Use groupId as both user_id and thread_id base for consistent storage
+    const userId = `lisa-${groupId}`;
+    const threadId = `lisa-memory-${groupId}`;
+    // Ensure user and thread exist
+    await zepEnsureUser(apiKey, userId);
+    await zepGetOrCreateThread(apiKey, threadId, userId);
+    // Add message to thread (Zep extracts facts automatically)
+    const result = await zepFetch(apiKey, `/threads/${encodeURIComponent(threadId)}/messages`, {
+        method: 'POST',
+        body: JSON.stringify({
+            messages: [
+                {
+                    role: 'user',
+                    role_type: 'user',
+                    content: `[${source}] ${text}`,
+                },
+            ],
+        }),
+    });
+    return { message_uuid: result.message_uuids?.[0] };
+}
+async function zepSearchFacts(apiKey, query, groupIds, limit) {
+    const allFacts = [];
+    // Search across all group IDs (hierarchical)
+    for (const groupId of groupIds) {
+        const userId = `lisa-${groupId}`;
+        try {
+            const result = await zepFetch(apiKey, '/graph/search', {
+                method: 'POST',
+                body: JSON.stringify({
+                    user_id: userId,
+                    query,
+                    limit: Math.ceil(limit / groupIds.length), // Distribute limit across groups
+                    search_scope: 'facts',
+                }),
+            });
+            // Transform edges to facts format
+            const facts = (result.edges || []).map((edge) => ({
+                uuid: edge.uuid,
+                name: edge.name,
+                fact: edge.fact,
+                created_at: edge.created_at,
+            }));
+            allFacts.push(...facts);
+        }
+        catch (_err) {
+            // Group might not exist yet, continue to next
+        }
+    }
+    // Sort by created_at descending and limit
+    allFacts.sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime());
+    return { facts: allFacts.slice(0, limit) };
+}
+// ============================================================================
+// End Zep Cloud Client
+// ============================================================================
+// Entity type to tag mapping
+const TYPE_MAP = {
+    // Code & Architecture
+    'decision': 'code:decision',
+    'pattern': 'code:pattern',
+    'dependency': 'code:dependency',
+    'tech-debt': 'code:tech-debt',
+    // Context & History
+    'bug': 'context:bug',
+    'rationale': 'context:rationale',
+    'failed': 'context:failed',
+    'quirk': 'context:quirk',
+    // External
+    'feedback': 'external:feedback',
+    'incident': 'external:incident',
+    'contract': 'external:contract',
+    // People & Process
+    'contributor': 'people:contributor',
+    'review': 'people:review',
+    'blocker': 'people:blocker',
+    'estimate': 'people:estimate',
+    // Project
+    'scope-in': 'project:scope-in',
+    'scope-out': 'project:scope-out',
+    'milestone': 'project:milestone',
+    'init-review': 'type:init-review',
+};
+// Auto-detect prefixes in text
+const PREFIX_MAP = {
+    'DECISION:': 'code:decision',
+    'PATTERN:': 'code:pattern',
+    'TECH-DEBT:': 'code:tech-debt',
+    'BUG:': 'context:bug',
+    'RATIONALE:': 'context:rationale',
+    'FAILED:': 'context:failed',
+    'INCIDENT:': 'external:incident',
+    'BLOCKER:': 'people:blocker',
+    'SCOPE-IN:': 'project:scope-in',
+    'SCOPE-OUT:': 'project:scope-out',
+    'INIT-REVIEW:': 'type:init-review',
+};
+function detectPrefixTag(text) {
+    for (const [prefix, tag] of Object.entries(PREFIX_MAP)) {
+        if (text.toUpperCase().startsWith(prefix)) {
+            return tag;
+        }
+    }
+    return null;
+}
+const args = process.argv.slice(2);
+const env = (() => {
+    // Read from .agents/skills/.env (2 levels up from memory/scripts/)
+    const envPath = path.join(__dirname, '..', '..', '.env');
+    const out = {};
+    try {
+        const raw = fs.readFileSync(envPath, 'utf8');
+        raw.split(/\r?\n/).forEach((line) => {
+            if (!line || line.startsWith('#'))
+                return;
+            const idx = line.indexOf('=');
+            if (idx === -1)
+                return;
+            const key = line.slice(0, idx).trim();
+            const val = line.slice(idx + 1).trim();
+            out[key] = val;
+        });
+    }
+    catch (_) {
+        // optional .env; ignore if missing
+    }
+    return out;
+})();
+function popFlag(name, fallback) {
+    const idx = args.indexOf(name);
+    if (idx === -1)
+        return fallback;
+    const val = args[idx + 1];
+    args.splice(idx, 2);
+    return val ?? fallback;
+}
+function hasFlag(name) {
+    const idx = args.indexOf(name);
+    if (idx === -1)
+        return false;
+    args.splice(idx, 1);
+    return true;
+}
+const command = args.shift() ?? '';
+const endpoint = popFlag('--endpoint', env.GRAPHITI_ENDPOINT || process.env.GRAPHITI_ENDPOINT || 'http://localhost:8010/mcp/');
+// Group ID: explicit --group > env > folder-based (current directory)
+const explicitGroup = popFlag('--group', null);
+const envGroup = env.GRAPHITI_GROUP_ID || process.env.GRAPHITI_GROUP_ID;
+const groupId = explicitGroup || envGroup || getCurrentGroupId();
+// Track if group was explicitly configured (CLI or env) vs auto-detected
+const hasConfiguredGroup = !!(explicitGroup || envGroup);
+const query = popFlag('--query', '');
+const limit = Number(popFlag('--limit', '10')) || 10;
+const explicitTag = popFlag('--tag', null);
+const entityType = popFlag('--type', null);
+const source = popFlag('--source', 'skill:load-memory');
+const useCache = hasFlag('--cache');
+const payload = args.join(' ').trim();
+const cacheFile = path.join(__dirname, '..', 'cache', 'memory.log');
+// Mode detection
+const graphitiMode = env.STORAGE_MODE || process.env.STORAGE_MODE || 'local';
+const zepApiKey = env.ZEP_API_KEY || process.env.ZEP_API_KEY || '';
+const isZepCloud = graphitiMode === 'zep-cloud';
+// Resolve tag: explicit --tag > --type mapping > prefix detection > undefined
+function resolveTag(text) {
+    if (explicitTag)
+        return explicitTag;
+    if (entityType && TYPE_MAP[entityType])
+        return TYPE_MAP[entityType];
+    const prefixTag = detectPrefixTag(text);
+    if (prefixTag)
+        return prefixTag;
+    return undefined;
+}
+async function initialize() {
+    const body = {
+        jsonrpc: '2.0',
+        id: 'init',
+        method: 'initialize',
+        params: {
+            protocolVersion: '2024-11-05',
+            capabilities: {
+                experimental: {},
+                prompts: { listChanged: false },
+                resources: { subscribe: false, listChanged: false },
+                tools: { listChanged: false },
+            },
+            clientInfo: { name: 'memory-skill', version: '0.1.0' },
+        },
+    };
+    const resp = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            // Graphiti requires clients to accept both JSON responses and event streams.
+            Accept: 'application/json, text/event-stream',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!resp.ok)
+        throw new Error(`initialize failed: ${resp.status}`);
+    const sid = resp.headers.get('mcp-session-id');
+    if (!sid)
+        throw new Error('missing mcp-session-id');
+    return sid;
+}
+async function rpcCall(method, params, sessionId) {
+    const payload = method === 'initialize' || method === 'ping' || method.startsWith('tools/')
+        ? { jsonrpc: '2.0', id: '1', method, params }
+        : { jsonrpc: '2.0', id: '1', method: 'tools/call', params: { name: method, arguments: params } };
+    const resp = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'MCP-SESSION-ID': sessionId,
+            Accept: 'application/json, text/event-stream',
+        },
+        body: JSON.stringify(payload),
+    });
+    let text = await resp.text();
+    // MCP servers may wrap JSON in Server-Sent Events; unwrap the data line if present.
+    if (text.startsWith('event:')) {
+        const dataLine = text.split('\n').find((l) => l.startsWith('data:'));
+        if (dataLine)
+            text = dataLine.slice(5).trim();
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`bad JSON: ${text.slice(0, 160)}`);
+    }
+    if (!resp.ok || data.error)
+        throw new Error(data?.error?.message || `HTTP ${resp.status}`);
+    return data.result?.structuredContent?.result || data.result || data;
+}
+async function addMemory(sessionId) {
+    if (!payload)
+        throw new Error('add requires text payload');
+    const resolvedTag = resolveTag(payload);
+    const params = {
+        name: payload.slice(0, 80),
+        episode_body: payload,
+        source,
+        group_id: groupId,
+        tags: resolvedTag ? [resolvedTag] : undefined,
+    };
+    await rpcCall('add_memory', params, sessionId);
+    return { status: 'ok', action: 'add', group: groupId, text: payload, tag: resolvedTag };
+}
+async function loadMemory(sessionId) {
+    // Use configured group (CLI or env) if available, otherwise use hierarchical groups
+    const groupIds = hasConfiguredGroup ? [groupId] : getHierarchicalGroupIds();
+    const params = { query: query || '*', max_facts: limit, group_ids: groupIds };
+    const result = await rpcCall('search_memory_facts', params, sessionId);
+    const facts = result?.facts || result?.result?.facts || [];
+    return { status: 'ok', action: 'load', group: groupId, groups: groupIds, query, facts };
+}
+// ============================================================================
+// Zep Cloud Mode Functions (no MCP/Docker required)
+// ============================================================================
+async function addMemoryZep() {
+    if (!payload)
+        throw new Error('add requires text payload');
+    if (!zepApiKey)
+        throw new Error('ZEP_API_KEY required for zep-cloud mode');
+    const resolvedTag = resolveTag(payload);
+    // Include tag in the text for Zep (Zep extracts facts from message content)
+    const textWithTag = resolvedTag ? `[${resolvedTag}] ${payload}` : payload;
+    const result = await zepAddMemory(zepApiKey, textWithTag, groupId, source);
+    return {
+        status: 'ok',
+        action: 'add',
+        group: groupId,
+        text: payload,
+        tag: resolvedTag,
+        message_uuid: result.message_uuid,
+        mode: 'zep-cloud',
+    };
+}
+async function loadMemoryZep() {
+    if (!zepApiKey)
+        throw new Error('ZEP_API_KEY required for zep-cloud mode');
+    // Use configured group (CLI or env) if available, otherwise use hierarchical groups
+    const groupIds = hasConfiguredGroup ? [groupId] : getHierarchicalGroupIds();
+    const result = await zepSearchFacts(zepApiKey, query || '*', groupIds, limit);
+    return {
+        status: 'ok',
+        action: 'load',
+        group: groupId,
+        groups: groupIds,
+        query,
+        facts: result.facts,
+        mode: 'zep-cloud',
+    };
+}
+function writeCache(obj) {
+    try {
+        const line = JSON.stringify({ ts: new Date().toISOString(), ...obj });
+        fs.appendFileSync(cacheFile, `${line}\n`, 'utf8');
+    }
+    catch (err) {
+        // cache failures should not crash command
+    }
+}
+function readCacheFallback() {
+    try {
+        const data = fs.readFileSync(cacheFile, 'utf8').trim().split('\n').filter(Boolean);
+        if (!data.length)
+            return null;
+        return data.slice(-1).map((l) => JSON.parse(l))[0];
+    }
+    catch (err) {
+        return null;
+    }
+}
+async function main() {
+    try {
+        if (!['add', 'load'].includes(command))
+            throw new Error('command must be add|load');
+        let out;
+        if (isZepCloud) {
+            // Zep Cloud mode: use native REST API (no Docker/MCP required)
+            out = command === 'add' ? await addMemoryZep() : await loadMemoryZep();
+        }
+        else {
+            // MCP mode: local (requires Docker MCP server)
+            const sid = await initialize();
+            out = command === 'add' ? await addMemory(sid) : await loadMemory(sid);
+        }
+        if (useCache)
+            writeCache(out);
+        console.log(JSON.stringify(out, null, 2));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const fallback = useCache ? readCacheFallback() : null;
+        if (fallback) {
+            console.log(JSON.stringify({ status: 'fallback', error: message, fallback }, null, 2));
+            return;
+        }
+        console.error(message);
+        process.exit(1);
+    }
+}
+main();

package/dist/templates/agents/skills/prompt/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: prompt
+description: "Capture each prompt into Graphiti memory (episodes) for this repo/user."
+---
+
+## Purpose
+Store every prompt (and optional role/kind) as a memory episode in Graphiti MCP, so agents can recall recent context.
+
+## Triggers
+- "load prompt", "capture prompt", or any per-prompt hook integration
+- Use when you want every prompt stored automatically.
+
+## Usage
+- `node scripts/prompt.js add --text "..." [--role user|assistant] [--kind Direction|Decision|Requirement|Observation] [--force]`
+- By default uses `GRAPHITI_ENDPOINT` and `GRAPHITI_GROUP_ID` from `.agents/.env`. Falls back to `http://localhost:8010/mcp/` and `lisa`.
+
+## Notes
+- Adds a fingerprint tag to avoid duplicate prompts unless `--force` is passed.
+- Output: JSON with status/action.