aaak-vault-sync 1.0.0

package/README.md

@@ -0,0 +1,294 @@
+# aaak-vault-sync
+
+Sync your Obsidian vault to AAAK format for LLM memory loading. Converts markdown files into compact symbolic summaries that any LLM can scan to load relevant context from your vault.
+
+AAAK encoding is provided by [`dialect.py`](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/dialect.py) from the [mempalace](https://github.com/milla-jovovich/mempalace) project.
+
+## How it works
+
+1. `aaak-scan` walks your Obsidian vault and converts each `.md` file to AAAK format using `dialect.py` — a lossy summarization that extracts entities, topics, key sentences, emotions, and flags into a token-efficient representation
+2. Output files are written to `$VAULT/aaak/` alongside a human/LLM-readable index (`aaak_index.md`)
+3. A generic prompt template can be used with any LLM to check the index and follow relevant entries to their AAAK summaries (or the original markdown if needed)
+4. An optional Claude integration can install a skill and CLAUDE.md rule
+5. A launchd agent (macOS) keeps the index updated hourly in the background
+
+**AAAK is lossy** — it summarizes, not compresses. The original files are always preserved. AAAK files point back to their source via a `SOURCE:` header line.
+
+## Requirements
+
+- Python 3.7+
+- Node.js 14+ (for the CLI shim and setup script)
+- macOS (for the launchd scheduler, Linux/Windows users can set up a cron job manually)
+- Optional: [Claude Code](https://claude.ai/code) if you want the `/scan-vault` skill and CLAUDE.md memory rule
+
+## Installation
+
+```bash
+npm install -g aaak-vault-sync
+```
+
+Or clone and install locally:
+
+```bash
+git clone https://github.com/yourname/aaak-vault-sync
+cd aaak-vault-sync
+npm install -g .
+```
+
+## Setup
+
+### 1. Set your vault path
+
+Add to your shell profile (`~/.zshrc` or `~/.bashrc`):
+
+```bash
+export OBSIDIAN_VAULT_PATH=/path/to/your/vault
+```
+
+Reload your shell:
+
+```bash
+source ~/.zshrc
+```
+
+### 2. Run setup
+
+```bash
+npm run setup
+```
+
+This installs two generic things:
+
+| What | Where |
+|------|-------|
+| launchd agent (hourly sync) | `~/Library/LaunchAgents/com.aaak.vault-sync.plist` |
+| generic memory-loader prompt | `~/.aaak/generic-memory-loader.md` |
+
+Optional Claude integration:
+
+```bash
+npm run setup -- --target claude
+```
+
+That also installs:
+
+| What | Where |
+|------|-------|
+| Claude Code skill (`/scan-vault`) | `~/.claude/skills/scan-vault/SKILL.md` |
+| CLAUDE.md memory rule | `~/.claude/CLAUDE.md` (appended) |
+
+### 3. Activate the scheduler
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.aaak.vault-sync.plist
+```
+
+### 4. Run an initial sync
+
+```bash
+aaak-scan --verbose
+```
+
+This scans your vault, generates AAAK files in `$VAULT/aaak/`, and writes both `aaak_index.md` and `aaak_index.json`.
+
+## Usage
+
+### CLI
+
+```bash
+# Sync new and updated files
+aaak-scan
+
+# Show what would change without writing anything
+aaak-scan --dry-run
+
+# Verbose output
+aaak-scan --verbose
+
+# Force re-scan all files (ignore mtime)
+aaak-scan --force
+
+# Combine flags
+aaak-scan --dry-run --verbose
+```
+
+### Generic LLM integration
+
+After setup, you can use this prompt file with any LLM app that supports system prompts or custom instructions:
+
+- `~/.aaak/generic-memory-loader.md`
+
+That prompt tells the model to:
+
+1. Read `$OBSIDIAN_VAULT_PATH/aaak/aaak_index.md`
+2. Scan the Topics column for relevant entries
+3. Read linked AAAK summaries
+4. Fall back to original markdown via `SOURCE:` if needed
+5. Optionally use `aaak_index.json` for structured tooling
+
+### Claude Code skill
+
+Once setup is complete, invoke from any Claude Code session:
+
+```
+/scan-vault
+```
+
+Reports how many files were converted, updated, or skipped.
+
+### Memory loading
+
+For any LLM, use the generated prompt file at `~/.aaak/generic-memory-loader.md`.
+
+If you installed the Claude integration, every Claude Code session automatically:
+
+1. Reads `$OBSIDIAN_VAULT_PATH/aaak/aaak_index.md`
+2. Scans the Topics column for entries relevant to the current task
+3. Reads linked AAAK files for compressed summaries of relevant docs
+4. Follows `SOURCE:` lines to original markdown if full detail is needed
+
+If `OBSIDIAN_VAULT_PATH` is not set, this step is silently skipped.
+
+## Vault output structure
+
+After the first sync, your vault will contain:
+
+```
+your-vault/
+└── aaak/
+    ├── aaak_index.md          ← LLM-readable index + embedded JSON for sync tracking
+    ├── aaak_index.json        ← Tool-friendly structured index
+    ├── entities.json          ← Auto-detected proper noun → code mappings
+    ├── note-title.aaak.md     ← Compressed AAAK summary of note-title.md
+    └── folder--nested.aaak.md ← Nested paths use -- as separator
+```
+
+Each `.aaak.md` file starts with a `SOURCE:` line pointing back to the original:
+
+```
+SOURCE: projects/my-project.md
+?|?|2026-04-07|my-project
+0:ALJ+PRF|project_launch_decision|"We decided to launch in Q2"|determ|DECISION
+```
+
+The `aaak_index.md` table looks like:
+
+| Source | AAAK | Last Scanned | Topics |
+|--------|------|--------------|--------|
+| `projects/my-project.md` | `aaak/projects--my-project.aaak.md` | 2026-04-07 | project_launch_decision |
+
+## AAAK format
+
+AAAK is defined in `dialect.py`, which is part of [mempalace](https://github.com/milla-jovovich/mempalace) — a broader LLM memory system. The `dialect.py` included here is sourced from [`mempalace/dialect.py`](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/dialect.py).
+
+The dialect is a structured symbolic summary:
+
+```
+FILE_NUM|PRIMARY_ENTITY|DATE|TITLE              ← Header
+ZID:ENTITIES|topic_keywords|"key_quote"|WEIGHT|EMOTIONS|FLAGS  ← Zettel
+T:ZID<->ZID|label                              ← Tunnel (connection)
+ARC:emotion->emotion->emotion                  ← Emotional arc
+```
+
+**Emotion codes**: `joy`, `fear`, `trust`, `grief`, `wonder`, `rage`, `love`, `hope`, `despair`, `peace`, `anx`, `determ`, `convict`, `frust`, `curious`, `grat`, `satis`, `excite`, and more.
+
+**Flags**: `ORIGIN`, `CORE`, `SENSITIVE`, `PIVOT`, `GENESIS`, `DECISION`, `TECHNICAL`
+
+Any LLM reads AAAK natively — no special decoder required.
+
+## Entity detection
+
+`aaak-scan` automatically detects proper nouns (people, organizations, project names) across your vault and assigns stable 3-character codes:
+
+- `Alice Johnson` → `ALJ`
+- `Project Falcon` → `PRF`
+- `Bob Smith` → `BOS`
+
+Codes are saved to `$VAULT/aaak/entities.json` and stay stable across runs — new entities are appended, existing codes are never changed.
+
+## Configuration
+
+All configuration is via environment variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OBSIDIAN_VAULT_PATH` | Yes | Absolute path to your Obsidian vault |
+
+No config files needed. The scanner is intentionally zero-config beyond the vault path.
+
+## Scheduling
+
+### macOS (launchd)
+
+The setup script installs a launchd agent that runs `aaak-scan` every hour.
+
+```bash
+# Check status
+launchctl list | grep aaak
+
+# View logs
+cat /tmp/aaak-vault-sync.log
+cat /tmp/aaak-vault-sync.err
+
+# Stop
+launchctl unload ~/Library/LaunchAgents/com.aaak.vault-sync.plist
+
+# Start again
+launchctl load ~/Library/LaunchAgents/com.aaak.vault-sync.plist
+```
+
+To change the interval, edit `~/Library/LaunchAgents/com.aaak.vault-sync.plist` and update `StartInterval` (in seconds). Then reload:
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.aaak.vault-sync.plist
+launchctl load ~/Library/LaunchAgents/com.aaak.vault-sync.plist
+```
+
+### Linux / Windows (cron)
+
+Add a cron job:
+
+```bash
+crontab -e
+```
+
+```
+0 * * * * OBSIDIAN_VAULT_PATH=/path/to/vault aaak-scan >> /tmp/aaak-vault-sync.log 2>&1
+```
+
+## Uninstall
+
+```bash
+# Stop the scheduler
+launchctl unload ~/Library/LaunchAgents/com.aaak.vault-sync.plist
+rm ~/Library/LaunchAgents/com.aaak.vault-sync.plist
+
+# Remove the Claude skill
+rm -rf ~/.claude/skills/scan-vault
+
+# Remove from CLAUDE.md (delete the "## Obsidian Vault Memory" section)
+# Then uninstall the package
+npm uninstall -g aaak-vault-sync
+```
+
+The `$VAULT/aaak/` directory is not removed, so your AAAK files stay in the vault.
+
+## Project structure
+
+```
+aaak-vault-sync/
+├── bin/
+│   └── aaak-scan.js          ← CLI entry point (Node shim → python scan.py)
+├── scripts/
+│   └── setup.js              ← Installs plist, skill, CLAUDE.md rule
+├── templates/
+│   ├── com.aaak.vault-sync.plist.template
+│   └── scan-vault-skill.md.template
+├── scan.py                   ← Core vault scanner
+├── dialect.py                ← AAAK format encoder/decoder
+└── package.json
+```
+
+## License
+
+MIT

package/bin/aaak-scan.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const scanPy = path.join(__dirname, '..', 'scan.py');
+const args = process.argv.slice(2);
+
+const result = spawnSync('python3', [scanPy, ...args], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+if (result.error) {
+  if (result.error.code === 'ENOENT') {
+    console.error('Error: python3 not found. Install Python 3 and ensure it is on your PATH.');
+  } else {
+    console.error('Error:', result.error.message);
+  }
+  process.exit(1);
+}
+
+process.exit(result.status ?? 0);