ihow-memory 0.1.0-alpha.0

package/dist/mcp/server.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env -S node --experimental-strip-types
+import readline from 'node:readline';
+import { openCore } from '../core.js';
+function parseWorkspaceArgs(argv) {
+    const options = {};
+    for(let index = 0; index < argv.length; index += 1){
+        if (argv[index] === '--space') options.space = argv[++index];
+        else if (argv[index] === '--root') options.root = argv[++index];
+        else if (argv[index] === '--memory-root') options.memoryRoot = argv[++index];
+        else if (argv[index] === '--state-root') options.stateRoot = argv[++index];
+        else if (argv[index] === '--cwd') options.cwd = argv[++index];
+        else if (argv[index] === '--engine') options.engine = argv[++index];
+        else if (argv[index] === '--vector-provider-command') options.vectorProviderCommand = argv[++index];
+        else if (argv[index] === '--vector-model') options.vectorModel = argv[++index];
+        else if (argv[index] === '--vector-timeout-ms') options.vectorTimeoutMs = Number(argv[++index]);
+    }
+    return options;
+}
+function send(value) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+function result(id, value) {
+    send({
+        jsonrpc: '2.0',
+        id,
+        result: value
+    });
+}
+function error(id, code, message) {
+    send({
+        jsonrpc: '2.0',
+        id,
+        error: {
+            code,
+            message
+        }
+    });
+}
+const TOOL_DEFINITIONS = [
+    {
+        name: 'memory.search',
+        description: 'Search local iHow Memory with FTS. Returns citation path and snippet.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string'
+                },
+                limit: {
+                    type: 'number'
+                }
+            },
+            required: [
+                'query'
+            ]
+        }
+    },
+    {
+        name: 'memory.read',
+        description: 'Read a memory markdown file by path and return exact content plus citation.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ref: {
+                    type: 'string'
+                }
+            },
+            required: [
+                'ref'
+            ]
+        }
+    },
+    {
+        name: 'memory.write_candidate',
+        description: 'Write a memory candidate into the sandbox inbox. Does not write durable memory.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                text: {
+                    type: 'string'
+                },
+                title: {
+                    type: 'string'
+                },
+                sourceAgent: {
+                    type: 'string'
+                },
+                metadata: {
+                    type: 'object'
+                }
+            },
+            required: [
+                'text'
+            ]
+        }
+    },
+    {
+        name: 'memory.promote',
+        description: 'Promote a candidate into governed staging with an audit event. Existing workspace mode uses memory/_mcp/promoted only.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                candidate: {
+                    type: 'string'
+                },
+                target: {
+                    type: 'object'
+                }
+            },
+            required: [
+                'candidate'
+            ]
+        }
+    },
+    {
+        name: 'memory.durable_promote',
+        description: 'Run a governed durable promote. Requires explicit dryRun=true or realWrite=true.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                candidate: {
+                    type: 'string'
+                },
+                dryRun: {
+                    type: 'boolean'
+                },
+                realWrite: {
+                    type: 'boolean'
+                },
+                actor: {
+                    type: 'string'
+                },
+                target: {
+                    type: 'object'
+                }
+            },
+            required: [
+                'candidate'
+            ]
+        }
+    },
+    {
+        name: 'memory.status',
+        description: 'Return workspace, local FTS provider, index, and sync status.',
+        inputSchema: {
+            type: 'object',
+            properties: {}
+        }
+    }
+];
+async function main() {
+    const core = await openCore(parseWorkspaceArgs(process.argv.slice(2)));
+    const rl = readline.createInterface({
+        input: process.stdin,
+        crlfDelay: Infinity
+    });
+    rl.on('line', async (line)=>{
+        if (!line.trim()) return;
+        let request;
+        try {
+            request = JSON.parse(line);
+        } catch  {
+            error(null, -32700, 'parse_error');
+            return;
+        }
+        try {
+            const id = request.id ?? null;
+            const params = request.params || {};
+            if (request.method === 'initialize') {
+                result(id, {
+                    protocolVersion: '2024-11-05',
+                    serverInfo: {
+                        name: 'ihow-memory-core',
+                        version: '0.0.1-a0.1'
+                    },
+                    capabilities: {
+                        tools: {}
+                    }
+                });
+            } else if (request.method?.startsWith('notifications/')) {
+                return;
+            } else if (request.method === 'tools/list') {
+                result(id, {
+                    tools: TOOL_DEFINITIONS
+                });
+            } else if (request.method === 'tools/call') {
+                const name = String(params.name || '');
+                const args = params.arguments || {};
+                let payload;
+                if (name === 'memory.search') {
+                    payload = await core.search(String(args.query || ''), {
+                        limit: Number(args.limit || 5)
+                    });
+                } else if (name === 'memory.read') {
+                    payload = await core.read(String(args.ref || ''));
+                } else if (name === 'memory.write_candidate') {
+                    payload = await core.write_candidate(args);
+                } else if (name === 'memory.promote') {
+                    payload = await core.promote(String(args.candidate || ''), args.target || {});
+                } else if (name === 'memory.durable_promote') {
+                    payload = await core.durable_promote(String(args.candidate || ''), {
+                        dryRun: args.dryRun === true,
+                        realWrite: args.realWrite === true,
+                        actor: typeof args.actor === 'string' ? args.actor : 'mcp',
+                        target: args.target || {}
+                    });
+                } else if (name === 'memory.status') {
+                    payload = await core.status();
+                } else {
+                    throw new Error('unknown_tool');
+                }
+                result(id, {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(payload, null, 2)
+                        }
+                    ],
+                    structuredContent: payload
+                });
+            } else {
+                error(id, -32601, 'method_not_found');
+            }
+        } catch (caught) {
+            error(request.id ?? null, -32000, caught instanceof Error ? caught.message : String(caught));
+        }
+    });
+}
+main().catch((caught)=>{
+    console.error(caught instanceof Error ? caught.message : String(caught));
+    process.exitCode = 1;
+});
+
+
+//# sourceURL=mcp/server.ts

package/dist/store/events.js

@@ -0,0 +1,17 @@
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { appendFileAtomic } from './files.js';
+export async function appendEvent(workspace, event) {
+    const fullEvent = {
+        id: crypto.randomUUID(),
+        at: new Date().toISOString(),
+        ...event
+    };
+    const day = fullEvent.at.slice(0, 10);
+    const logPath = path.join(workspace.eventsDir, `${day}.ndjson`);
+    await appendFileAtomic(logPath, `${JSON.stringify(fullEvent)}\n`);
+    return fullEvent;
+}
+
+
+//# sourceURL=store/events.ts

package/dist/store/files.js

@@ -0,0 +1,61 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { absoluteFromMemoryPath, relativeToSpace } from '../workspace.js';
+export async function atomicWriteFile(filePath, content) {
+    await fs.mkdir(path.dirname(filePath), {
+        recursive: true
+    });
+    const tmpPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+    await fs.writeFile(tmpPath, content, 'utf8');
+    await fs.rename(tmpPath, filePath);
+}
+export async function appendFileAtomic(filePath, line) {
+    await fs.mkdir(path.dirname(filePath), {
+        recursive: true
+    });
+    await fs.appendFile(filePath, line, 'utf8');
+}
+export async function readMemoryFile(workspace, ref) {
+    const absolutePath = absoluteFromMemoryPath(workspace, ref);
+    const content = await fs.readFile(absolutePath, 'utf8');
+    return {
+        path: relativeToSpace(workspace, absolutePath),
+        content
+    };
+}
+export async function listMarkdownFiles(root) {
+    const results = [];
+    async function visit(dir) {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, {
+                withFileTypes: true
+            });
+        } catch (error) {
+            if (error.code === 'ENOENT') return;
+            throw error;
+        }
+        for (const entry of entries){
+            const absolute = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === '_events') continue;
+                await visit(absolute);
+            } else if (entry.isFile() && entry.name.endsWith('.md')) {
+                results.push(absolute);
+            }
+        }
+    }
+    await visit(root);
+    return results.sort();
+}
+export function nowCompact() {
+    return new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+export function safeFileSlug(input, fallback = 'memory') {
+    const slug = input.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/-+/g, '-').replace(/^[-.]+|[-.]+$/g, '');
+    return (slug || fallback).slice(0, 80);
+}
+
+
+//# sourceURL=store/files.ts

package/dist/store/lock.js

@@ -0,0 +1,35 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const LOCK_RETRY_MS = 25;
+const LOCK_TIMEOUT_MS = 5000;
+function sleep(ms) {
+    return new Promise((resolve)=>setTimeout(resolve, ms));
+}
+export async function withWorkspaceLock(workspace, fn) {
+    await fs.mkdir(path.dirname(workspace.lockPath), {
+        recursive: true
+    });
+    const started = Date.now();
+    let handle;
+    while(!handle){
+        try {
+            handle = await fs.open(workspace.lockPath, 'wx');
+            await handle.writeFile(`${process.pid}\n${new Date().toISOString()}\n`, 'utf8');
+        } catch (error) {
+            if (error.code !== 'EEXIST') throw error;
+            if (Date.now() - started > LOCK_TIMEOUT_MS) throw new Error('workspace_lock_timeout');
+            await sleep(LOCK_RETRY_MS);
+        }
+    }
+    try {
+        return await fn();
+    } finally{
+        await handle.close();
+        await fs.rm(workspace.lockPath, {
+            force: true
+        });
+    }
+}
+
+
+//# sourceURL=store/lock.ts

package/dist/telemetry.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+const CONFIG_DIR = path.join(os.homedir(), '.ihow-memory');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'telemetry.json');
+const EVENTS_PATH = path.join(CONFIG_DIR, 'telemetry-events.jsonl');
+const ALLOWED_PROP_KEYS = [
+    'runtime',
+    'version',
+    'errorType'
+];
+function freshConfig() {
+    return {
+        enabled: false,
+        anonId: crypto.randomBytes(8).toString('hex'),
+        asked: false
+    };
+}
+export async function readConfig() {
+    try {
+        const parsed = JSON.parse(await fs.readFile(CONFIG_PATH, 'utf8'));
+        if (parsed && typeof parsed === 'object') return parsed;
+        return null;
+    } catch  {
+        return null;
+    }
+}
+async function writeConfig(cfg) {
+    await fs.mkdir(CONFIG_DIR, {
+        recursive: true
+    });
+    await fs.writeFile(CONFIG_PATH, `${JSON.stringify(cfg, null, 2)}\n`, 'utf8');
+}
+export async function isEnabled() {
+    const cfg = await readConfig();
+    return cfg?.enabled === true;
+}
+export async function hasAsked() {
+    const cfg = await readConfig();
+    return cfg?.asked === true;
+}
+export async function setEnabled(enabled) {
+    const cfg = await readConfig() || freshConfig();
+    cfg.enabled = enabled;
+    cfg.asked = true;
+    await writeConfig(cfg);
+}
+export async function markAsked() {
+    const cfg = await readConfig() || freshConfig();
+    cfg.asked = true;
+    await writeConfig(cfg);
+}
+export async function track(event, props = {}) {
+    try {
+        if (!await isEnabled()) return;
+        const safe = {
+            event: String(event),
+            ts: new Date().toISOString()
+        };
+        for (const key of ALLOWED_PROP_KEYS){
+            const value = props[key];
+            if (typeof value === 'string' && value.length > 0 && value.length < 64) safe[key] = value;
+        }
+        await fs.mkdir(CONFIG_DIR, {
+            recursive: true
+        });
+        await fs.appendFile(EVENTS_PATH, `${JSON.stringify(safe)}\n`, 'utf8');
+    } catch  {}
+}
+export async function status() {
+    const cfg = await readConfig();
+    return {
+        enabled: cfg?.enabled === true,
+        asked: cfg?.asked === true,
+        anonId: cfg?.anonId ? `${cfg.anonId.slice(0, 4)}…` : null,
+        collects: [
+            'event',
+            'runtime',
+            'version',
+            'errorType',
+            'ts'
+        ],
+        neverCollects: [
+            'memory content',
+            'file names',
+            'queries',
+            'paths',
+            'prompts',
+            'any user data'
+        ],
+        endpoint: 'local-only — not uploaded (opt-in framework; real endpoint TBD)',
+        configPath: CONFIG_PATH
+    };
+}
+
+
+//# sourceURL=telemetry.ts

package/dist/types.js

@@ -0,0 +1,3 @@
+
+
+//# sourceURL=types.ts

package/dist/workspace.js

@@ -0,0 +1,151 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { defaultFtsManifest } from './engine/manifest.js';
+const DEFAULT_ROOT = path.join(os.homedir(), '.ihow-memory');
+export function defaultRoot() {
+    return process.env.IHOW_MEMORY_HOME || DEFAULT_ROOT;
+}
+export function defaultMemoryRoot() {
+    return process.env.MEMORY_ROOT || process.env.IHOW_MEMORY_ROOT;
+}
+export function defaultStateRoot() {
+    return process.env.IHOW_MEMORY_STATE_ROOT || path.join(process.cwd(), '.state');
+}
+export function slugifySpace(input) {
+    const normalized = input.trim().toLowerCase().replace(/\\/g, '/').replace(/[^a-z0-9._/-]+/g, '-').replace(/[/]+/g, '-').replace(/-+/g, '-').replace(/^[-.]+|[-.]+$/g, '');
+    if (normalized) return normalized.slice(0, 80);
+    return `space-${crypto.createHash('sha256').update(input).digest('hex').slice(0, 12)}`;
+}
+export function resolveSpace(options = {}) {
+    if (options.space) return slugifySpace(options.space);
+    const cwd = path.resolve(options.cwd || process.cwd());
+    const base = path.basename(cwd) || 'workspace';
+    const hash = crypto.createHash('sha256').update(cwd).digest('hex').slice(0, 8);
+    return slugifySpace(`${base}-${hash}`);
+}
+export function resolveWorkspace(options = {}) {
+    const memoryRoot = options.memoryRoot || defaultMemoryRoot();
+    if (memoryRoot) return resolveExistingMemoryRootWorkspace(options, memoryRoot);
+    const root = path.resolve(options.root || defaultRoot());
+    const space = resolveSpace(options);
+    const spaceDir = path.join(root, space);
+    const memoryDir = path.join(spaceDir, 'memory');
+    const mcpDir = path.join(memoryDir, '_mcp');
+    const eventsDir = path.join(memoryDir, '_events');
+    const historyDir = path.join(spaceDir, 'history');
+    return {
+        mode: 'managed-space',
+        root,
+        space,
+        spaceDir,
+        memoryDir,
+        mcpDir,
+        candidatesDir: path.join(memoryDir, 'candidate', 'inbox'),
+        promotedDir: path.join(mcpDir, 'promoted'),
+        eventsDir,
+        historyDir,
+        indexPath: path.join(spaceDir, 'index.sqlite'),
+        indexManifestPath: path.join(spaceDir, 'index-manifest.json'),
+        lockPath: path.join(spaceDir, '.lock')
+    };
+}
+function resolveExistingMemoryRootWorkspace(options, memoryRoot) {
+    const memoryDir = path.resolve(memoryRoot);
+    const stateRoot = path.resolve(options.stateRoot || defaultStateRoot());
+    const space = resolveSpace({
+        space: options.space || path.basename(path.dirname(memoryDir)) || 'workspace-memory',
+        cwd: options.cwd
+    });
+    const spaceDir = path.join(stateRoot, space);
+    const mcpDir = path.join(memoryDir, '_mcp');
+    return {
+        mode: 'existing-memory-root',
+        root: stateRoot,
+        space,
+        spaceDir,
+        memoryDir,
+        mcpDir,
+        candidatesDir: path.join(mcpDir, 'candidates'),
+        promotedDir: path.join(mcpDir, 'promoted'),
+        eventsDir: path.join(mcpDir, '_events'),
+        historyDir: path.join(mcpDir, 'history'),
+        indexPath: path.join(spaceDir, 'index.sqlite'),
+        indexManifestPath: path.join(spaceDir, 'index-manifest.json'),
+        lockPath: path.join(spaceDir, '.lock')
+    };
+}
+export async function ensureWorkspace(workspace) {
+    await fs.mkdir(workspace.candidatesDir, {
+        recursive: true
+    });
+    await fs.mkdir(workspace.promotedDir, {
+        recursive: true
+    });
+    if (workspace.mode === 'managed-space') {
+        await fs.mkdir(path.join(workspace.memoryDir, 'scopes'), {
+            recursive: true
+        });
+    }
+    await fs.mkdir(workspace.eventsDir, {
+        recursive: true
+    });
+    await fs.mkdir(workspace.historyDir, {
+        recursive: true
+    });
+    await fs.mkdir(path.dirname(workspace.indexPath), {
+        recursive: true
+    });
+    await ensureIndexManifest(workspace);
+    return workspace;
+}
+export async function ensureIndexManifest(workspace, status = 'ready') {
+    try {
+        await fs.access(workspace.indexManifestPath);
+        return;
+    } catch  {
+        const manifest = defaultFtsManifest(status === 'ready' ? 'ready' : 'missing');
+        await fs.writeFile(workspace.indexManifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+    }
+}
+export function relativeToSpace(workspace, absolutePath) {
+    const resolved = path.resolve(absolutePath);
+    const memoryDir = path.resolve(workspace.memoryDir);
+    if (resolved === memoryDir || resolved.startsWith(`${memoryDir}${path.sep}`)) {
+        const rel = path.relative(memoryDir, resolved).split(path.sep).join('/');
+        return rel ? `memory/${rel}` : 'memory';
+    }
+    return path.relative(workspace.spaceDir, resolved).split(path.sep).join('/');
+}
+export function absoluteFromMemoryPath(workspace, ref) {
+    const normalized = ref.replace(/\\/g, '/').replace(/^\/+/, '');
+    const withoutSpace = normalized.startsWith(`${workspace.space}/`) ? normalized.slice(workspace.space.length + 1) : normalized;
+    let rel = withoutSpace;
+    if (rel.startsWith('memory/')) {
+        rel = rel.slice('memory/'.length);
+    } else {
+        const memoryDirRef = path.resolve(rel);
+        const memoryDir = path.resolve(workspace.memoryDir);
+        if (path.isAbsolute(rel) && (memoryDirRef === memoryDir || memoryDirRef.startsWith(`${memoryDir}${path.sep}`))) {
+            rel = path.relative(memoryDir, memoryDirRef);
+        }
+    }
+    const absolute = path.resolve(workspace.memoryDir, rel);
+    const memoryDir = path.resolve(workspace.memoryDir);
+    if (absolute !== memoryDir && !absolute.startsWith(`${memoryDir}${path.sep}`)) {
+        throw new Error('path_outside_memory_workspace');
+    }
+    return absolute;
+}
+export function relativeToMemory(workspace, absolutePath) {
+    return path.relative(workspace.memoryDir, absolutePath).split(path.sep).join('/');
+}
+export function isMcpSandboxPath(workspace, absolutePath) {
+    const resolved = path.resolve(absolutePath);
+    const sandbox = path.resolve(workspace.mcpDir);
+    return resolved === sandbox || resolved.startsWith(`${sandbox}${path.sep}`);
+}
+
+
+//# sourceURL=workspace.ts

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "ihow-memory",
+  "version": "0.1.0-alpha.0",
+  "type": "module",
+  "description": "Local-first shared memory for AI agents with zero-dependency FTS, citations, governance, and MCP.",
+  "keywords": [
+    "ai",
+    "agent",
+    "memory",
+    "mcp",
+    "local-first",
+    "sqlite",
+    "fts",
+    "codex",
+    "claude-code",
+    "cursor"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iHow1/ihow-memory-core.git"
+  },
+  "homepage": "https://github.com/iHow1/ihow-memory-core#readme",
+  "bugs": {
+    "url": "https://github.com/iHow1/ihow-memory-core/issues"
+  },
+  "files": [
+    "bin/",
+    "dist/cli.js",
+    "dist/core.js",
+    "dist/types.js",
+    "dist/workspace.js",
+    "dist/governance.js",
+    "dist/telemetry.js",
+    "dist/engine/",
+    "dist/store/",
+    "dist/mcp/",
+    "dist/http/console.js",
+    "LICENSE",
+    "NOTICE",
+    "TRADEMARK.md",
+    "README.md"
+  ],
+  "bin": {
+    "ihow-memory": "bin/ihow-memory.mjs",
+    "ihow-memory-mcp": "dist/mcp/server.js"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "node scripts/build-dist.mjs",
+    "precli": "npm run build",
+    "cli": "node bin/ihow-memory.mjs",
+    "mcp": "node --experimental-strip-types src/mcp/server.ts",
+    "preactivation-proof": "npm run build",
+    "activation-proof": "node scripts/activation-proof.mjs",
+    "proof": "node scripts/proof.mjs",
+    "dogfood": "node scripts/dogfood-proof.mjs",
+    "prepack": "npm run build"
+  },
+  "license": "Apache-2.0"
+}