@aperdomoll90/ledger-ai 1.0.0

package/README.md

@@ -0,0 +1,120 @@
+# @aperdomoll90/ledger-ai
+
+Your AI, everywhere. One identity, one memory, every device.
+
+Ledger stores who you are, how you work, and what you know in a single knowledge base. Connect any AI agent — Claude, OpenClaw, ChatGPT — and it immediately knows your rules, preferences, and context. Switch devices and pick up where you left off.
+
+## Install
+
+```bash
+npm install -g @aperdomoll90/ledger-ai
+```
+
+Requires Node.js 20+.
+
+## Quick Start
+
+```bash
+# 1. Set up credentials and database
+ledger init
+
+# 2. Connect your AI agent
+ledger setup claude    # Claude Code (live sync, MCP, hooks)
+ledger setup openclaw  # OpenClaw (persona files, CLI sync)
+ledger setup chatgpt   # ChatGPT (static system prompt export)
+
+# 3. Create your persona
+ledger onboard
+```
+
+Second device? Same Ledger, same persona:
+
+```bash
+npm install -g @aperdomoll90/ledger-ai
+ledger init            # connect to existing Supabase project
+ledger setup claude    # pull persona, install hooks
+```
+
+## What It Does
+
+**For you:** Define who you are, how you want AI to behave, your coding conventions, communication style. Do it once. Every AI agent on every device follows the same rules.
+
+**For your agents:** Semantic search over your knowledge base. Notes are embedded with OpenAI and stored in Postgres with pgvector. Agents find relevant context by meaning, not keywords.
+
+**For your workflow:** Automatic sync at session start, conflict detection, session-end checks. Hooks enforce rules (block credential file access, auto-ingest notes to Ledger).
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `ledger init` | Set up credentials and database schema |
+| `ledger setup <platform>` | Configure an agent (claude, openclaw, chatgpt) |
+| `ledger onboard` | Create your persona (interactive wizard) |
+| `ledger pull` | Download notes from Ledger to local cache |
+| `ledger push <file>` | Upload a local file to Ledger |
+| `ledger check` | Compare local files vs Ledger |
+| `ledger show <query>` | Search by meaning, open matching note |
+| `ledger export <query>` | Download a note to any path (untracked) |
+| `ledger ingest [file]` | Add files to Ledger with duplicate detection |
+| `ledger backup` | Backup all notes to ~/.ledger/backups/ |
+| `ledger restore <file>` | Restore from backup |
+| `ledger config list` | View settings |
+| `ledger config set <key> <value>` | Change settings |
+
+## Stack
+
+- **Database:** Supabase (hosted Postgres + pgvector) — free tier
+- **Embeddings:** OpenAI `text-embedding-3-small`
+- **Protocol:** MCP (Model Context Protocol) for Claude Code
+- **CLI:** Commander, TypeScript, ES modules
+- **Sync:** SHA-256 content hashing, conflict detection
+
+## How It Works
+
+```
+Your devices / agents
+    |
+    v
+ledger CLI ←→ Supabase (Postgres + pgvector)
+    |
+    ├── pull: download notes → local cache files + CLAUDE.md
+    ├── push: upload local changes → Ledger (re-embeds)
+    ├── check: compare hashes, detect drift
+    ├── show: semantic search → open in editor
+    └── MCP server: Claude Code talks to Ledger natively
+```
+
+Notes are stored with content + metadata + vector embeddings. Search finds relevant notes by meaning. Sync uses SHA-256 content hashes to detect changes without markers.
+
+## Platforms
+
+| Platform | Connection | Sync |
+|---|---|---|
+| Claude Code | MCP (live) + hooks | Bidirectional, automatic |
+| OpenClaw | CLI | Bidirectional via `ledger` commands |
+| ChatGPT | None | Static snapshot, re-run to update |
+
+## Requirements
+
+- Node.js 20+
+- Supabase project (free tier works)
+- OpenAI API key (for embeddings, ~$0.02/1M tokens)
+
+## Known Limitations
+
+- **Embeddings require OpenAI** — currently uses `text-embedding-3-small` only. Supabase built-in embeddings (free, no API key) and multi-provider support planned for v2.0.
+- **Anthropic has no embedding API** — Claude is for text generation. Even Claude users need an OpenAI key for embeddings.
+- **English-optimized** — semantic search works best with English content. Multilingual support depends on the embedding model.
+
+## Roadmap
+
+- Multi-provider embeddings (Supabase built-in, OpenAI, others)
+- Note versioning / history
+- Soft delete (trash)
+- Multi-format ingest (PDF, Excel, images, audio)
+- Web dashboard
+- VS Code extension
+
+## License
+
+ISC

package/dist/cli.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { loadConfig } from './lib/config.js';
+import { pull } from './commands/pull.js';
+import { push } from './commands/push.js';
+import { check } from './commands/check.js';
+import { show } from './commands/show.js';
+import { exportNote } from './commands/export.js';
+import { ingest } from './commands/ingest.js';
+import { init } from './commands/init.js';
+import { setupClaudeCode, setupOpenclaw, setupChatgpt } from './commands/setup.js';
+import { backup, enableBackupCron, disableBackupCron } from './commands/backup.js';
+import { restore } from './commands/restore.js';
+import { onboard } from './commands/onboard.js';
+import { configGet, configSet, configList } from './commands/config.js';
+process.on('unhandledRejection', (err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});
+const program = new Command();
+program
+    .name('ledger')
+    .description('AI identity and memory system — sync knowledge across agents and devices')
+    .version('1.0.0');
+program
+    .command('pull')
+    .description('Download notes from Ledger to local cache')
+    .option('-q, --quiet', 'suppress non-conflict output')
+    .option('-f, --force', 'overwrite local changes without conflict check')
+    .action(async (options) => {
+    const config = loadConfig();
+    await pull(config, { quiet: options.quiet ?? false, force: options.force ?? false });
+});
+program
+    .command('push <file>')
+    .description('Upload a local file to Ledger')
+    .action(async (file) => {
+    const config = loadConfig();
+    await push(config, file);
+});
+program
+    .command('check')
+    .description('Compare local files vs Ledger, report sync status')
+    .action(async () => {
+    const config = loadConfig();
+    await check(config);
+});
+program
+    .command('show <query...>')
+    .description('Search Ledger by meaning, open matching note')
+    .option('-t, --type <type>', 'filter by note type (e.g. feedback, reference)')
+    .option('-p, --project <project>', 'filter by project name')
+    .action(async (queryParts, options) => {
+    const config = loadConfig();
+    await show(config, queryParts.join(' '), { type: options.type, project: options.project });
+});
+program
+    .command('export <query...>')
+    .description('Download a note to a custom location (untracked)')
+    .option('-o, --output <path>', 'output directory (default: current directory)')
+    .action(async (queryParts, options) => {
+    const config = loadConfig();
+    await exportNote(config, queryParts.join(' '), options.output);
+});
+program
+    .command('ingest [file]')
+    .description('Scan for unknown files and add them to Ledger with duplicate detection')
+    .option('-a, --auto', 'auto-ingest without prompts (for hooks)')
+    .action(async (file, options) => {
+    const config = loadConfig();
+    await ingest(config, { file, auto: options.auto ?? false });
+});
+program
+    .command('backup')
+    .description('Backup all notes to ~/.ledger/backups/')
+    .option('-q, --quiet', 'suppress output unless error')
+    .option('--enable-cron', 'enable daily backup at 1am')
+    .option('--disable-cron', 'disable daily backup cron')
+    .action(async (options) => {
+    if (options.enableCron) {
+        enableBackupCron();
+        return;
+    }
+    if (options.disableCron) {
+        disableBackupCron();
+        return;
+    }
+    const config = loadConfig();
+    await backup(config, { quiet: options.quiet ?? false });
+});
+program
+    .command('restore <file>')
+    .description('Restore notes from a backup JSON file')
+    .action(async (file) => {
+    const config = loadConfig();
+    await restore(config, file);
+});
+const configCmd = program
+    .command('config')
+    .description('View or change Ledger settings');
+configCmd
+    .command('get <key>')
+    .description('Get a config value (or "all" for full config)')
+    .action(async (key) => {
+    await configGet(key);
+});
+configCmd
+    .command('set <key> <value>')
+    .description('Set a config value')
+    .action(async (key, value) => {
+    await configSet(key, value);
+});
+configCmd
+    .command('list')
+    .description('Show all settings')
+    .action(async () => {
+    await configList();
+});
+program
+    .command('onboard')
+    .description('Create your AI persona (profile, communication style, rules)')
+    .action(async () => {
+    const config = loadConfig();
+    await onboard(config);
+});
+program
+    .command('init')
+    .description('Set up Ledger on this machine (credentials, database schema)')
+    .action(async () => {
+    await init();
+});
+const setupCmd = program
+    .command('setup')
+    .description('Configure an agent platform to use Ledger');
+setupCmd
+    .command('claude-code')
+    .description('Register MCP, install hooks, pull cache (live sync)')
+    .action(async () => {
+    await setupClaudeCode();
+});
+setupCmd
+    .command('openclaw [path]')
+    .description('Generate persona files for OpenClaw (live sync via CLI)')
+    .action(async (path) => {
+    await setupOpenclaw(path);
+});
+setupCmd
+    .command('chatgpt')
+    .description('Generate system prompt for ChatGPT (static snapshot)')
+    .action(async () => {
+    await setupChatgpt();
+});
+program.parse();

package/dist/commands/backup.js

@@ -0,0 +1,89 @@
+import { writeFileSync, mkdirSync, readdirSync, unlinkSync } from 'fs';
+import { resolve } from 'path';
+import { execFileSync, spawnSync } from 'child_process';
+import { getLedgerDir } from '../lib/config.js';
+export async function backup(config, options) {
+    const { quiet } = options;
+    const backupDir = resolve(getLedgerDir(), 'backups');
+    mkdirSync(backupDir, { recursive: true });
+    // Fetch all notes (not just cached)
+    const { data, error } = await config.supabase
+        .from('notes')
+        .select('id, content, metadata, created_at, updated_at')
+        .order('id', { ascending: true });
+    if (error) {
+        console.error(`Backup failed: ${error.message}`);
+        process.exit(1);
+    }
+    if (!data || data.length === 0) {
+        if (!quiet)
+            console.error('No notes to backup.');
+        return;
+    }
+    const date = new Date().toISOString().split('T')[0];
+    const filePath = resolve(backupDir, `${date}.json`);
+    writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n');
+    // Keep last 5 backups, delete older
+    const backups = readdirSync(backupDir)
+        .filter(f => f.endsWith('.json'))
+        .sort()
+        .reverse();
+    for (const old of backups.slice(5)) {
+        unlinkSync(resolve(backupDir, old));
+        if (!quiet)
+            console.error(`  deleted old backup: ${old}`);
+    }
+    if (!quiet) {
+        console.error(`Backed up ${data.length} notes to ${filePath}`);
+    }
+    console.log(filePath);
+}
+export function enableBackupCron() {
+    const cronLine = '0 1 * * * ledger backup --quiet';
+    // Check if already in crontab
+    let existing = '';
+    try {
+        existing = execFileSync('crontab', ['-l'], { encoding: 'utf-8' });
+    }
+    catch {
+        // No crontab yet
+    }
+    if (existing.includes('ledger backup')) {
+        console.error('Backup cron already enabled.');
+        return;
+    }
+    const newCrontab = existing.trimEnd() + '\n' + cronLine + '\n';
+    try {
+        const result = spawnSync('crontab', ['-'], { input: newCrontab, stdio: ['pipe', 'pipe', 'pipe'] });
+        if (result.status !== 0)
+            throw new Error(result.stderr?.toString() || 'crontab failed');
+        console.error('Daily backup enabled (1am). View with `crontab -l`.');
+    }
+    catch (e) {
+        console.error(`Failed to set cron: ${e.message}`);
+        console.error(`Add manually: ${cronLine}`);
+    }
+}
+export function disableBackupCron() {
+    let existing = '';
+    try {
+        existing = execFileSync('crontab', ['-l'], { encoding: 'utf-8' });
+    }
+    catch {
+        console.error('No crontab found.');
+        return;
+    }
+    const filtered = existing
+        .split('\n')
+        .filter(line => !line.includes('ledger backup'))
+        .join('\n');
+    try {
+        const result = spawnSync('crontab', ['-'], { input: filtered, stdio: ['pipe', 'pipe', 'pipe'] });
+        if (result.status !== 0)
+            throw new Error(result.stderr?.toString() || 'crontab failed');
+        console.error('Backup cron disabled.');
+    }
+    catch (e) {
+        console.error(`Failed to update cron: ${e.message}`);
+    }
+}

package/dist/commands/check.js

@@ -0,0 +1,79 @@
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { fetchNoteHashes } from '../lib/notes.js';
+import { contentHash } from '../lib/hash.js';
+export async function check(config) {
+    const result = {
+        files: [],
+        clean: 0,
+        modified: 0,
+        upstream: 0,
+        conflicts: 0,
+        unknown: 0,
+        deleted: 0,
+    };
+    if (!existsSync(config.memoryDir)) {
+        console.error('Memory directory not found. Run `ledger pull` first.');
+        return result;
+    }
+    const noteHashes = await fetchNoteHashes(config.supabase);
+    const notesByFile = new Map(noteHashes.map(n => [n.localFile, n]));
+    const localFiles = readdirSync(config.memoryDir)
+        .filter(f => f.endsWith('.md') && f !== 'MEMORY.md');
+    for (const file of localFiles) {
+        const filePath = resolve(config.memoryDir, file);
+        const localContent = readFileSync(filePath, 'utf-8').trim();
+        const localHash = contentHash(localContent);
+        const note = notesByFile.get(file);
+        if (!note) {
+            console.error(`  ${file} — unknown (not in Ledger)`);
+            result.files.push({ file, state: 'unknown' });
+            result.unknown++;
+            notesByFile.delete(file);
+            continue;
+        }
+        const ledgerHash = contentHash(note.content);
+        const storedHash = note.contentHash;
+        const localChanged = localHash !== storedHash;
+        const ledgerChanged = ledgerHash !== storedHash;
+        if (!localChanged && !ledgerChanged) {
+            console.error(`  ${file} — in sync`);
+            result.files.push({ file, state: 'clean', noteId: note.id });
+            result.clean++;
+        }
+        else if (localChanged && !ledgerChanged) {
+            console.error(`  ${file} — modified locally`);
+            result.files.push({ file, state: 'modified', noteId: note.id });
+            result.modified++;
+        }
+        else if (!localChanged && ledgerChanged) {
+            console.error(`  ${file} — updated in Ledger`);
+            result.files.push({ file, state: 'upstream', noteId: note.id });
+            result.upstream++;
+        }
+        else {
+            console.error(`  ${file} — CONFLICT (both changed)`);
+            result.files.push({ file, state: 'conflict', noteId: note.id });
+            result.conflicts++;
+        }
+        notesByFile.delete(file);
+    }
+    for (const [file, note] of notesByFile) {
+        console.error(`  ${file} — missing locally (exists in Ledger)`);
+        result.files.push({ file, state: 'deleted', noteId: note.id });
+        result.deleted++;
+    }
+    const summary = [
+        `${result.clean} clean`,
+        result.modified > 0 ? `${result.modified} modified` : null,
+        result.upstream > 0 ? `${result.upstream} upstream` : null,
+        result.conflicts > 0 ? `${result.conflicts} conflicts` : null,
+        result.unknown > 0 ? `${result.unknown} unknown` : null,
+        result.deleted > 0 ? `${result.deleted} deleted` : null,
+    ].filter(Boolean).join(', ');
+    console.log(`Check: ${summary}`);
+    if (result.modified === 0 && result.conflicts === 0 && result.unknown === 0 && result.upstream === 0 && result.deleted === 0) {
+        console.log('All synced.');
+    }
+    return result;
+}

package/dist/commands/config.js

@@ -0,0 +1,115 @@
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { getLedgerDir } from '../lib/config.js';
+import { confirm } from '../lib/prompt.js';
+const CONFIG_PATH = resolve(getLedgerDir(), 'config.json');
+function loadFullConfig() {
+    if (existsSync(CONFIG_PATH)) {
+        try {
+            return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+        }
+        catch {
+            return {};
+        }
+    }
+    return {};
+}
+function saveConfig(config) {
+    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+}
+const SECURITY_WARNINGS = {
+    envBlocking: 'This disables .env file protection.\nYour API keys and credentials will be readable by the AI agent.',
+    mcpJsonBlocking: 'This allows direct editing of mcp.json.\nMCP servers should be registered via `claude mcp add`, not by editing config files.',
+};
+const DESCRIPTIONS = {
+    envBlocking: 'Block reading/writing .env and credential files',
+    mcpJsonBlocking: 'Block direct editing of mcp.json',
+    writeInterception: 'Auto-ingest files written to memory directory into Ledger',
+    sessionEndCheck: 'Check for unsynced files at session end',
+};
+export async function configGet(key) {
+    const config = loadFullConfig();
+    if (key === 'all') {
+        console.log(JSON.stringify(config, null, 2));
+        return;
+    }
+    // Check hooks
+    const hookKey = key;
+    if (hookKey in (config.hooks || {})) {
+        console.log(`${key}: ${config.hooks?.[hookKey]}`);
+        return;
+    }
+    // Check top-level
+    if (key in config) {
+        console.log(`${key}: ${config[key]}`);
+        return;
+    }
+    // Show default
+    const defaults = {
+        envBlocking: true,
+        mcpJsonBlocking: true,
+        writeInterception: true,
+        sessionEndCheck: true,
+    };
+    if (key in defaults) {
+        console.log(`${key}: ${defaults[key]} (default)`);
+        return;
+    }
+    console.error(`Unknown config key: ${key}`);
+    console.error(`Available: ${Object.keys(DESCRIPTIONS).join(', ')}, memoryDir, claudeMdPath, all`);
+    process.exit(1);
+}
+export async function configSet(key, value) {
+    const config = loadFullConfig();
+    // Handle hook settings
+    const hookKeys = ['envBlocking', 'mcpJsonBlocking', 'writeInterception', 'sessionEndCheck'];
+    if (hookKeys.includes(key)) {
+        const boolValue = value === 'true';
+        // Disabling a security feature — warn and double confirm
+        if (!boolValue && key in SECURITY_WARNINGS) {
+            console.error(`\nWARNING: ${SECURITY_WARNINGS[key]}\n`);
+            const first = await confirm('Are you sure?');
+            if (!first) {
+                console.error('Cancelled.');
+                return;
+            }
+            const second = await confirm(`Confirm: disable ${key}?`);
+            if (!second) {
+                console.error('Cancelled.');
+                return;
+            }
+        }
+        if (!config.hooks)
+            config.hooks = {};
+        config.hooks[key] = boolValue;
+        saveConfig(config);
+        const state = boolValue ? 'enabled' : 'disabled';
+        console.error(`${key}: ${state}`);
+        console.error('Run `ledger setup claude-code` to apply hook changes.');
+        return;
+    }
+    // Handle path settings
+    if (key === 'memoryDir' || key === 'claudeMdPath') {
+        config[key] = value;
+        saveConfig(config);
+        console.error(`${key}: ${value}`);
+        return;
+    }
+    console.error(`Unknown config key: ${key}`);
+    console.error(`Available: ${hookKeys.join(', ')}, memoryDir, claudeMdPath`);
+    process.exit(1);
+}
+export async function configList() {
+    const config = loadFullConfig();
+    const hooks = config.hooks || {};
+    console.error('Hook settings:');
+    for (const [key, desc] of Object.entries(DESCRIPTIONS)) {
+        const value = hooks[key] ?? true;
+        const state = value ? 'enabled' : 'DISABLED';
+        console.error(`  ${key}: ${state} — ${desc}`);
+    }
+    console.error('\nPaths:');
+    console.error(`  memoryDir: ${config.memoryDir || '(default)'}`);
+    console.error(`  claudeMdPath: ${config.claudeMdPath || '(default)'}`);
+    console.error('\nConfig file: ' + CONFIG_PATH);
+}

package/dist/commands/export.js

@@ -0,0 +1,21 @@
+import { writeFileSync, mkdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { searchNotes } from '../lib/notes.js';
+import { fatal, ExitCode } from '../lib/errors.js';
+export async function exportNote(config, query, outputPath) {
+    const results = await searchNotes(config.supabase, config.openai, query);
+    if (results.length === 0) {
+        fatal('No matching notes found.', ExitCode.NOTE_NOT_FOUND);
+    }
+    const note = results[0];
+    const upsertKey = note.metadata.upsert_key || `note-${note.id}`;
+    const filename = `${upsertKey}.md`;
+    const targetPath = outputPath
+        ? resolve(outputPath, filename)
+        : resolve(process.cwd(), filename);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, note.content + '\n', 'utf-8');
+    // No hash stored — export is untracked
+    console.log(`Exported "${upsertKey}" → ${targetPath}`);
+    console.log(targetPath);
+}