diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cb5e366 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,91 @@ + + +# lucid-memory + +## Purpose +Local AI memory MCP server providing persistent, reconstructive memory for AI coding assistants. Combines a high-performance Rust retrieval engine (ACT-R spreading activation + MINERVA 2 reconstructive memory) with a TypeScript MCP server. 2.7ms retrieval, $0/query, no cloud dependency. Packaged as a single install for Claude Code, OpenAI Codex, and OpenCode. + +## Key Files +| File | Description | +|------|-------------| +| `package.json` | Bun workspace root; build/test/lint/bench scripts for all packages | +| `Cargo.toml` | Rust workspace; shared deps and version pinning across all crates | +| `HOW_IT_WORKS.md` | Architecture and algorithm deep-dive | +| `ROADMAP.md` | Planned features and milestones | +| `install.sh` / `install.ps1` | End-user install scripts (macOS/Linux and Windows) | +| `uninstall.sh` / `uninstall.ps1` | End-user uninstall scripts | +| `biome.json` | TypeScript lint/format config (Biome) | +| `rustfmt.toml` / `clippy.toml` | Rust format and lint config | +| `tsconfig.json` | TypeScript compiler config (shared) | + +## Subdirectories +| Directory | Purpose | +|-----------|---------| +| `crates/` | Rust crates: retrieval engine and N-API bindings (see `crates/AGENTS.md`) | +| `packages/` | TypeScript packages: MCP server and pre-built native binaries (see `packages/AGENTS.md`) | +| `benchmarks/` | Quality and performance benchmarks (see `benchmarks/AGENTS.md`) | +| `scripts/` | Build, install, and release automation scripts | +| `.github/` | CI/CD workflows for build, test, and publish | +| `.claude/` | Claude Code project configuration | + +## For AI Agents + +### Working In This Directory +- Stack: **Bun + Rust + TypeScript** monorepo. Keep Rust build steps and JS tooling separate. +- Build: `bun run build` (Rust first, then TS). Test: `bun test`. Lint: `bun run lint`. +- Named exports only — no default exports anywhere in TypeScript. +- `timeout` unavailable on macOS — use `gtimeout`. +- Good code is self-explaining — comment only when the WHY is non-obvious. +- A TODO is COMPLETE only when all 5 gates pass: + +| Gate | Requirement | How To Verify | +|------|-------------|---------------| +| **1. Implemented** | Code written, compiles, no errors | `bun test` passes | +| **2. Wired** | Connected to systems that call it (wake cycles, hooks, handlers, prompts) | Grep for function calls from outside the module | +| **3. Tested** | Unit + integration tests covering happy path and edge cases | Test count documented, all pass | +| **4. Verified in Production** | Evidence of actual usage in the live database | SQL query showing non-zero rows, event counts, or call logs | +| **5. No Orphaned Outputs** | Every computed output consumed by at least one downstream system | Grep for each output → confirm a reader exists | + +### Testing Requirements +- `bun run test:rust` — Rust unit tests via `cargo test` +- `bun run test:ts` — Bun test runner across all TS packages +- `bun run bench` — full benchmark suite (optional, slow) +- Both test suites must pass before any change is complete. + +### Common Patterns +- Rust crates handle high-performance computation; TypeScript handles I/O and MCP protocol. +- N-API bindings (`lucid-napi`, `lucid-perception-napi`) bridge Rust computation to TypeScript. +- Pre-built `.node` binaries ship per platform in `packages/lucid-native` and `packages/lucid-perception`. +- Database stored at `~/.lucid/` — supports shared, per-client, and profile modes via `LUCID_CLIENT` env. + +## Dependencies + +### Internal +- `crates/lucid-core` → `crates/lucid-napi` → `packages/lucid-server` +- `crates/lucid-perception` → `crates/lucid-perception-napi` → `packages/lucid-server` + +### External +- Bun (runtime + test runner), TypeScript 5, Biome (lint/format) +- Rust toolchain, napi-rs CLI (N-API binding generation) +- `@modelcontextprotocol/sdk` (MCP protocol), `zod` (schema validation) +- FFmpeg CLI (video frame extraction), Whisper (optional audio transcription) + +### Domain Language Maintenance + +When editing documentation in this repo, consult these canonical definitions: + +| Term | Definition | +|------|-----------| +| **Memory** | A stored text trace with embedding, activation level, and access history | +| **Activation** | Composite score combining base-level (recency/frequency), probe similarity, and spreading | +| **Base-level activation** | B(m) = ln[Σ(t_k)^(-d)] — recency and frequency of past retrievals | +| **Probe** | The query embedding used to drive retrieval | +| **Spreading activation** | Activation flowing through the association graph: A_j = Σ(W_i/n_i) × S_ij | +| **Gist** | Compressed semantic essence of a verbatim memory trace | +| **Episode** | A temporally bounded sequence of memories representing a work session | +| **Consolidation** | Background process: strengthen recent memories, decay stale ones, prune weak associations | +| **Association** | Weighted edge between two memories in the association graph | +| **Location** | Spatial/temporal context attached to a memory (project, file, line, timestamp) | +| **Native module** | Pre-built `.node` binary exposing Rust computation via N-API | + + diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c44702..b2376fa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,108 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +#### OpenAI-Compatible Local Embedding Endpoints + +Lucid Memory now supports any OpenAI-compatible embedding server as a drop-in backend — Ollama, LM Studio, vLLM, and others — without an API key. + +**Key features:** + +- **`LUCID_EMBEDDING_URL`** — Set to any OpenAI-compatible base URL (e.g. `http://localhost:11434/v1`). Checked first, highest priority in provider detection. +- **`LUCID_EMBEDDING_MODEL`** — Override the embedding model name (e.g. `nomic-embed-text`). +- **API key optional** — Local endpoints work without authentication. +- **Long-context models** — Enables models like `nomic-embed-text` (8192-token context) as an alternative to the built-in BGE model (512-token limit). +- **Endpoint probing** — `isAvailable()` probes `/models` on custom endpoints to verify availability before committing. + +**Usage:** + +```bash +LUCID_EMBEDDING_URL=http://localhost:11434/v1 \ +LUCID_EMBEDDING_MODEL=nomic-embed-text \ +lucid-server +``` + +**Provider detection order:** `LUCID_EMBEDDING_URL` → local ONNX (BGE) → OpenAI → none. + +## [0.6.5] - 2026-02-20 + +### Added + +- **Linux ARM64 pre-built binary** for `lucid-native` (`lucid-native.linux-arm64-gnu.node`) — previously required building from source on Linux ARM64. + +### Fixed + +**All `.node` binaries shipped since January 30th were macOS ARM64 Mach-O files regardless of target platform**, causing immediate segfaults on Linux and Windows. Only macOS Apple Silicon users were unaffected. + +**Root cause:** Two interacting CI bugs: (1) the upload step used `path: *.node`, uploading all checked-out `.node` files per artifact rather than only the freshly built one; (2) the rename step picked the first `.node` file alphabetically from checkout — the pre-existing `darwin-arm64` binary — and renamed it to the target platform name, overwriting the correct build output. + +**Fixes:** + +- Clean stale binaries before building so only fresh build output exists +- Upload only the specific target file (`lucid-native.{platform}.node`) instead of `*.node` +- Add binary format validation (`file` command checks ELF/Mach-O/PE32+) in both publish and release jobs +- Add format validation to `install.sh` download fallback — wrong-format downloads are rejected and deleted +- Fix release job permissions for asset uploads + +Six layers now prevent recurrence: pre-build clean → post-build verify → targeted upload → publish validation → release validation → installer validation. + +**Platform support after this fix:** + +| Platform | lucid-native | lucid-perception | +|----------|:---:|:---:| +| macOS ARM64 (Apple Silicon) | pre-built | pre-built | +| macOS x64 (Intel) | build from source | pre-built | +| Linux x64 | pre-built | pre-built | +| Linux ARM64 | pre-built (new) | build from source | +| Windows x64 | pre-built | pre-built | + +## [0.6.4] - 2026-02-20 + +### Fixed + +#### Embedding Provider Diagnostics + +Silent embedding failures now surface with actionable diagnostics instead of falling through to `null`. + +- **`detectProvider()` returns `ProviderDiagnostics`** — per-provider failure reasons recorded; `lucid status` now shows exactly what was tried and why each provider was skipped (e.g. `Native: model failed to load (ORT error)`, `OpenAI: no OPENAI_API_KEY set`, `Ollama: connection refused`). Previously checked file existence only — a corrupt or incompatible model file would still show as "configured". +- **`retrieve()` returns `RetrievalResult`** — includes `method` (`"semantic"` | `"recency"`) and `warning` field. `memory_query` responses surface these fields so callers can detect when results are ranked by recency only due to embedding failure. + +## [0.6.3] - 2026-02-20 + +### Fixed + +- Switched built-in ONNX embedding model from FP16 (`model_fp16.onnx`) to INT8 quantized (`model_quantized.onnx`). The FP16 model contains graph optimizations (`SimplifiedLayerNormFusion`, `InsertedPrecisionFreeCast`) incompatible with `ort` 2.0.0-rc.11, causing embeddings to silently fail to load and report "No embedding provider configured". The quantized model (110MB vs 218MB) is fully compatible and produces equivalent retrieval quality. +- Installers now clean up the old FP16 model file on re-install. + +## [0.6.2] - 2026-02-15 + +### Fixed + +- Removed dead NAPI bindings that were exported but never called from TypeScript +- Removed orphaned struct fields causing Clippy warnings +- Resolved remaining Biome lint issues introduced by 0.6.1 + +## [0.6.1] - 2026-02-15 + +### Added + +- **`visual_list` MCP tool** — Browse and filter visual memories by project, media type, and recency. Previously `queryVisualMemories()` was unreachable from the MCP surface. + +### Fixed + +The 0.6.0 5-gate audit incorrectly made 5 storage methods private and deleted them to clear Biome lint errors, breaking wired features. This release restores and wires each: + +| Method | Wired to | +|--------|---------| +| `queryVisualMemories()` | New `visual_list` MCP tool | +| `getVisualEmbedding()` | Consolidation visual pruning guard (skip unprocessed visuals) | +| `getEpisode()` | Public API for single-episode lookup | +| `updateProjectContext()` | `store()` flow for project metadata accumulation | +| `hasEmbedding()` | Public API for per-memory embedding existence check | + +`memory_consolidation_status` enriched with episode diagnostics (recent episodes with event counts and boundary types) and pending embedding counts (memories awaiting background processing). + ## [0.6.0] - 2026-02-15 ### Added diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 916aaa1..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,33 +0,0 @@ -# Project: lucid-memory - -## Stack - -Bun, Rust, TypeScript - -## Navigation - -See `.claude/PROJECT_MAP.md` for project structure & key file locations. - -## Code Quality - -Good code is self explaining. Comment only when absolutely needed. - -## Conventions - -- Named exports, no default exports - -## Gotchas - -**timeout isn't available on macOS. Use gtimeout** - -## Complete - -A TODO is COMPLETE only when **all 5 gates** pass: - -| Gate | Requirement | How To Verify | -|------|-------------|---------------| -| **1. Implemented** | Code written, compiles, no errors | `bun test` passes | -| **2. Wired** | Connected to the systems that call it (wake cycles, hooks, handlers, prompts) | Grep for function calls from outside the module | -| **3. Tested** | Unit tests + integration tests covering happy path and edge cases | Test count documented, all pass | -| **4. Verified in Production** | Evidence of actual usage in the live database | SQL query showing non-zero rows, event counts, or call logs | -| **5. No Orphaned Outputs** | Every computed output is consumed by at least one downstream system | Grep for each output → confirm a reader exists | diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/GEMINI.md b/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/benchmarks/AGENTS.md b/benchmarks/AGENTS.md new file mode 100644 index 0000000..0f8f08c --- /dev/null +++ b/benchmarks/AGENTS.md @@ -0,0 +1,21 @@ + + + +# benchmarks + +## Purpose +Quality and performance benchmarks for the retrieval and memory systems. Measures recall, token efficiency, and retrieval quality against baselines (Claude-mem, Pinecone RAG, Traditional RAG). + +## Subdirectories +| Directory | Purpose | +|-----------|---------| +| `quality/` | TypeScript benchmark scripts for recall, RAG comparison, token efficiency, and episodic retrieval (see `quality/AGENTS.md`) | + +## For AI Agents + +### Working In This Directory +- Run via root scripts: `bun run bench:quality`, `bun run bench:rag`, `bun run bench:realistic`, `bun run bench:tokens`. +- Rust benchmarks live in `crates/lucid-core/benches/`; run with `bun run bench:rust`. +- Benchmarks are standalone scripts — no test framework, no assertions. Output is for human review. + + diff --git a/benchmarks/CLAUDE.md b/benchmarks/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/benchmarks/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/benchmarks/GEMINI.md b/benchmarks/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/benchmarks/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/benchmarks/quality/AGENTS.md b/benchmarks/quality/AGENTS.md new file mode 100644 index 0000000..8cec54a --- /dev/null +++ b/benchmarks/quality/AGENTS.md @@ -0,0 +1,27 @@ + + + +# benchmarks/quality + +## Purpose +Quality benchmarks measuring retrieval recall, token efficiency, and memory system performance against baseline approaches (Claude-mem, Pinecone RAG, Traditional RAG). + +## Key Files +| File | Description | +|------|-------------| +| `index.ts` | Main quality benchmark suite: recall@k, precision, F1 across retrieval strategies | +| `rag-comparison.ts` | Side-by-side comparison: lucid-memory vs Pinecone RAG vs Traditional RAG | +| `membrane-comparison.ts` | Comparison against membrane-style memory architectures | +| `realistic-dev.ts` | Simulates a realistic developer session with code questions and context switching | +| `episodic-e2e.ts` | End-to-end episodic memory benchmark: episode boundary detection accuracy | +| `token-efficiency.ts` | Token budget benchmarks: recall at fixed token counts (5x efficiency target) | + +## For AI Agents + +### Working In This Directory +- Run individual benchmarks: `bun run benchmarks/quality/.ts` +- Run all via root scripts: `bun run bench:quality`, `bun run bench:rag`, `bun run bench:realistic`, `bun run bench:tokens` +- Benchmarks use real retrieval calls — require initialized storage at `~/.lucid/`. +- Output is human-readable tables for comparison review, not assertions. + + diff --git a/benchmarks/quality/CLAUDE.md b/benchmarks/quality/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/benchmarks/quality/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/benchmarks/quality/GEMINI.md b/benchmarks/quality/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/benchmarks/quality/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/AGENTS.md b/crates/AGENTS.md new file mode 100644 index 0000000..a22136c --- /dev/null +++ b/crates/AGENTS.md @@ -0,0 +1,42 @@ + + + +# crates + +## Purpose +Rust workspace members providing the high-performance computation layer. Two independent subsystems: the memory retrieval engine (`lucid-core` + `lucid-napi`) and the visual perception pipeline (`lucid-perception` + `lucid-perception-napi`). Each subsystem ships a pure Rust crate and an N-API binding crate that exposes it to TypeScript. + +## Subdirectories +| Directory | Purpose | +|-----------|---------| +| `lucid-core/` | ACT-R spreading activation + MINERVA 2 retrieval engine (see `lucid-core/AGENTS.md`) | +| `lucid-napi/` | N-API bindings exposing lucid-core to Node.js/Bun (see `lucid-napi/AGENTS.md`) | +| `lucid-perception/` | Video frame extraction, scene detection, audio transcription (see `lucid-perception/AGENTS.md`) | +| `lucid-perception-napi/` | N-API bindings exposing lucid-perception to Node.js/Bun (see `lucid-perception-napi/AGENTS.md`) | + +## For AI Agents + +### Working In This Directory +- All crates are members of the Cargo workspace at the repo root. Never add a separate `[workspace]` block inside a crate. +- Shared dependencies are declared in root `Cargo.toml` under `[workspace.dependencies]`; crates reference them with `{ workspace = true }`. +- Lint rules (`[lints]`) are workspace-level; do not override per-crate without strong justification. + +### Testing Requirements +- `cargo test` from repo root runs all crate tests. +- `cargo bench -p lucid-core` runs lucid-core criterion benchmarks. +- `cargo clippy --all-targets --all-features` must pass clean. + +### Common Patterns +- Pure computation logic lives in the non-napi crate (`lucid-core`, `lucid-perception`). +- N-API crates contain only binding glue — no business logic. +- Optional heavy features (`embedding`, `transcription`, `cuda`) are feature-flagged; default build stays minimal. + +## Dependencies + +### External +- `napi` + `napi-derive` (N-API binding framework) +- `faer`, `nalgebra` (linear algebra), `rayon` (parallelism) +- `serde` + `rkyv` + `bincode` (serialization) +- `ort` + `tokenizers` (ONNX Runtime embedding, feature-gated) + + diff --git a/crates/CLAUDE.md b/crates/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/GEMINI.md b/crates/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-core/AGENTS.md b/crates/lucid-core/AGENTS.md new file mode 100644 index 0000000..77d7567 --- /dev/null +++ b/crates/lucid-core/AGENTS.md @@ -0,0 +1,55 @@ + + + +# lucid-core + +## Purpose +High-performance memory retrieval engine implementing ACT-R spreading activation and MINERVA 2 reconstructive memory model. Pure Rust library with no I/O or database dependencies — all computation, no side effects. Consumed by `lucid-napi` for TypeScript exposure. + +## Key Files +| File | Description | +|------|-------------| +| `Cargo.toml` | Crate manifest; `embedding` feature flag for ONNX Runtime support | +| `src/lib.rs` | Public API declarations and algorithm documentation | +| `src/activation.rs` | Base-level activation: recency/frequency decay B(m) = ln[Σ(t_k)^(-d)] | +| `src/embedding.rs` | Local ONNX-based embedding computation (requires `embedding` feature) | +| `src/location.rs` | Spatial and temporal location metadata for memories | +| `src/retrieval.rs` | Full retrieval pipeline: similarity → activation → spreading → rank | +| `src/spreading.rs` | Association graph traversal: A_j = Σ(W_i/n_i) × S_ij | +| `src/visual.rs` | Visual memory: image embedding retrieval support | + +## Subdirectories +| Directory | Purpose | +|-----------|---------| +| `src/` | All Rust source (see `src/AGENTS.md`) | +| `benches/` | Criterion benchmarks for activation and retrieval (see `benches/AGENTS.md`) | +| `examples/` | Runnable examples demonstrating retrieval and spreading activation (see `examples/AGENTS.md`) | + +## For AI Agents + +### Working In This Directory +- Pure computation — no filesystem access, no network, no database, no async. +- The `embedding` feature is optional; default build has no ONNX dependency. +- Retrieval pipeline order: cosine similarity → nonlinear activation A(i) = S(i)³ → base-level → spreading → combine → filter → rank. +- All public types implement `serde::{Serialize, Deserialize}`. + +### Testing Requirements +- `cargo test -p lucid-core` — unit tests +- `cargo bench -p lucid-core` — criterion benchmarks (activation, retrieval) +- `cargo clippy -p lucid-core --all-targets --all-features` — must pass clean + +### Common Patterns +- `smallvec` used for association lists to avoid heap allocation on small graphs. +- Benchmarks use `criterion` with `rand` for reproducible synthetic data. + +## Dependencies + +### Internal +- Consumed by `crates/lucid-napi` + +### External +- `serde`, `smallvec`, `thiserror` +- Optional: `ort` (ONNX Runtime), `tokenizers`, `ndarray`, `dirs`, `parking_lot` +- Dev: `criterion`, `rand` + + diff --git a/crates/lucid-core/CLAUDE.md b/crates/lucid-core/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-core/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-core/GEMINI.md b/crates/lucid-core/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-core/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-core/benches/AGENTS.md b/crates/lucid-core/benches/AGENTS.md new file mode 100644 index 0000000..d7ced35 --- /dev/null +++ b/crates/lucid-core/benches/AGENTS.md @@ -0,0 +1,22 @@ + + + +# lucid-core/benches + +## Purpose +Criterion benchmarks measuring performance of the activation and retrieval pipelines under synthetic load. + +## Key Files +| File | Description | +|------|-------------| +| `activation.rs` | Benchmarks for base-level activation computation at varying memory counts | +| `retrieval.rs` | Benchmarks for full retrieval pipeline: similarity, spreading, ranking | + +## For AI Agents + +### Working In This Directory +- Run with `cargo bench -p lucid-core`. +- Uses `criterion` with `rand` for reproducible synthetic data generation. +- Benchmark names match the function or module they measure — keep them aligned when refactoring. + + diff --git a/crates/lucid-core/benches/CLAUDE.md b/crates/lucid-core/benches/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-core/benches/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-core/benches/GEMINI.md b/crates/lucid-core/benches/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-core/benches/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-core/examples/AGENTS.md b/crates/lucid-core/examples/AGENTS.md new file mode 100644 index 0000000..c68ab48 --- /dev/null +++ b/crates/lucid-core/examples/AGENTS.md @@ -0,0 +1,22 @@ + + + +# lucid-core/examples + +## Purpose +Runnable examples demonstrating lucid-core API usage. Serve as integration smoke tests and onboarding material for the retrieval and spreading activation APIs. + +## Key Files +| File | Description | +|------|-------------| +| `basic_retrieval.rs` | Demonstrates store + retrieve with cosine similarity ranking | +| `spreading_activation.rs` | Demonstrates association graph construction and spreading activation | + +## For AI Agents + +### Working In This Directory +- Run with `cargo run --example basic_retrieval -p lucid-core`. +- Examples must compile and produce sensible output — treat as lightweight integration tests. +- Keep examples minimal and self-contained; no external dependencies beyond lucid-core. + + diff --git a/crates/lucid-core/examples/CLAUDE.md b/crates/lucid-core/examples/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-core/examples/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-core/examples/GEMINI.md b/crates/lucid-core/examples/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-core/examples/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-core/src/AGENTS.md b/crates/lucid-core/src/AGENTS.md new file mode 100644 index 0000000..16bbe8c --- /dev/null +++ b/crates/lucid-core/src/AGENTS.md @@ -0,0 +1,28 @@ + + + +# lucid-core/src + +## Purpose +Core retrieval engine implementation. Implements ACT-R spreading activation and MINERVA 2 reconstructive memory as pure Rust computation with no I/O. + +## Key Files +| File | Description | +|------|-------------| +| `lib.rs` | Module declarations and algorithm documentation | +| `activation.rs` | Base-level activation: recency + frequency decay B(m) = ln[Σ(t_k)^(-d)] | +| `embedding.rs` | Local ONNX-based embedding computation (requires `embedding` feature) | +| `location.rs` | Spatial and temporal location metadata attached to memories | +| `retrieval.rs` | Full retrieval pipeline: similarity → activation → spreading → rank | +| `spreading.rs` | Association graph traversal and spreading activation: A_j = Σ(W_i/n_i) × S_ij | +| `visual.rs` | Visual memory: image embedding retrieval support | + +## For AI Agents + +### Working In This Directory +- No I/O, no database access, no async — pure deterministic computation. +- Retrieval order: cosine similarity → nonlinear activation A(i) = S(i)³ → base-level → spreading → combine → filter by probability threshold → rank. +- The `embedding` feature gates ONNX Runtime — never assume it is always compiled in. +- `smallvec` used for association lists to avoid heap allocation on small graphs. + + diff --git a/crates/lucid-core/src/CLAUDE.md b/crates/lucid-core/src/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-core/src/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-core/src/GEMINI.md b/crates/lucid-core/src/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-core/src/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-napi/AGENTS.md b/crates/lucid-napi/AGENTS.md new file mode 100644 index 0000000..e6b1b09 --- /dev/null +++ b/crates/lucid-napi/AGENTS.md @@ -0,0 +1,40 @@ + + + +# lucid-napi + +## Purpose +N-API binding crate that exposes `lucid-core` to Node.js/Bun as a native `.node` module. Contains only binding glue — no business logic. Built with napi-rs; output binaries are distributed in `packages/lucid-native`. + +## Key Files +| File | Description | +|------|-------------| +| `Cargo.toml` | Crate manifest; depends on `lucid-core` and `napi`/`napi-derive` | +| `src/lib.rs` | All N-API exports — wraps lucid-core retrieval, activation, and spreading functions | + +## Subdirectories +| Directory | Purpose | +|-----------|---------| +| `src/` | N-API binding source (see `src/AGENTS.md`) | + +## For AI Agents + +### Working In This Directory +- All logic belongs in `lucid-core`, not here. This crate only converts types and marshals calls. +- Built via napi-rs CLI (`napi build --release`); output `.node` files go to `packages/lucid-native/`. +- Do not add business logic here — changes should be in `lucid-core` with bindings updated to match. +- Error handling: convert `lucid_core` errors to `napi::Error` with descriptive messages. + +### Testing Requirements +- Integration tested via `packages/lucid-server` TypeScript tests which import the compiled `.node` binary. +- No standalone Rust tests — binding correctness is verified at the TS integration layer. + +## Dependencies + +### Internal +- `crates/lucid-core` + +### External +- `napi`, `napi-derive`, `napi-build` + + diff --git a/crates/lucid-napi/CLAUDE.md b/crates/lucid-napi/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-napi/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-napi/GEMINI.md b/crates/lucid-napi/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-napi/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-napi/src/AGENTS.md b/crates/lucid-napi/src/AGENTS.md new file mode 100644 index 0000000..ceedb2f --- /dev/null +++ b/crates/lucid-napi/src/AGENTS.md @@ -0,0 +1,21 @@ + + + +# lucid-napi/src + +## Purpose +N-API binding glue connecting lucid-core Rust functions to the JavaScript/TypeScript interface. Converts Rust types to napi-rs JS-compatible types and delegates all computation to lucid-core. + +## Key Files +| File | Description | +|------|-------------| +| `lib.rs` | All N-API exports; wraps lucid-core retrieval, activation, and spreading functions | + +## For AI Agents + +### Working In This Directory +- Keep this file thin: type conversion and delegation only. No logic. +- Use `#[napi]` and `#[napi(object)]` macros from napi-derive for exports. +- Convert `lucid_core` errors to `napi::Error` with descriptive messages. + + diff --git a/crates/lucid-napi/src/CLAUDE.md b/crates/lucid-napi/src/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-napi/src/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-napi/src/GEMINI.md b/crates/lucid-napi/src/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-napi/src/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-perception-napi/AGENTS.md b/crates/lucid-perception-napi/AGENTS.md new file mode 100644 index 0000000..bafffe1 --- /dev/null +++ b/crates/lucid-perception-napi/AGENTS.md @@ -0,0 +1,38 @@ + + + +# lucid-perception-napi + +## Purpose +N-API binding crate exposing `lucid-perception` to Node.js/Bun as a native `.node` module. Binding glue only — no perception logic. Output binaries distributed in `packages/lucid-perception`. + +## Key Files +| File | Description | +|------|-------------| +| `Cargo.toml` | Crate manifest; depends on `lucid-perception` and `napi`/`napi-derive` | +| `src/lib.rs` | All N-API exports for the perception pipeline — frame extraction, scene detection, transcription | + +## Subdirectories +| Directory | Purpose | +|-----------|---------| +| `src/` | N-API binding source (see `src/AGENTS.md`) | + +## For AI Agents + +### Working In This Directory +- All perception logic belongs in `lucid-perception`, not here. +- Built via napi-rs CLI; output `.node` files go to `packages/lucid-perception/`. +- Frame extraction is async — use `napi::bindgen_prelude::AsyncTask` or tokio bridging pattern. + +### Testing Requirements +- Integration tested via `packages/lucid-server` TypeScript tests. + +## Dependencies + +### Internal +- `crates/lucid-perception` + +### External +- `napi`, `napi-derive`, `napi-build` + + diff --git a/crates/lucid-perception-napi/CLAUDE.md b/crates/lucid-perception-napi/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-perception-napi/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-perception-napi/GEMINI.md b/crates/lucid-perception-napi/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-perception-napi/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-perception-napi/src/AGENTS.md b/crates/lucid-perception-napi/src/AGENTS.md new file mode 100644 index 0000000..b1b0a0f --- /dev/null +++ b/crates/lucid-perception-napi/src/AGENTS.md @@ -0,0 +1,20 @@ + + + +# lucid-perception-napi/src + +## Purpose +N-API binding glue exposing lucid-perception frame extraction, scene detection, and transcription functions to JavaScript/TypeScript. + +## Key Files +| File | Description | +|------|-------------| +| `lib.rs` | All N-API exports; wraps lucid-perception pipeline with async bridging for frame extraction | + +## For AI Agents + +### Working In This Directory +- Keep thin — type conversion and async bridging only, no perception logic. +- Frame extraction is async — bridge to napi async task pattern. + + diff --git a/crates/lucid-perception-napi/src/CLAUDE.md b/crates/lucid-perception-napi/src/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-perception-napi/src/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-perception-napi/src/GEMINI.md b/crates/lucid-perception-napi/src/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-perception-napi/src/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-perception/AGENTS.md b/crates/lucid-perception/AGENTS.md new file mode 100644 index 0000000..58271cb --- /dev/null +++ b/crates/lucid-perception/AGENTS.md @@ -0,0 +1,47 @@ + + + +# lucid-perception + +## Purpose +Video processing pipeline for Lucid Memory: frame extraction via FFmpeg, scene change detection via perceptual hashing, and optional audio transcription via Whisper. Handles compute-intensive perception tasks in Rust while TypeScript manages I/O. Consumed by `lucid-perception-napi`. + +## Key Files +| File | Description | +|------|-------------| +| `Cargo.toml` | Crate manifest; `transcription` and `cuda` feature flags | +| `src/lib.rs` | Public API — `extract_frames`, `detect_scenes`, transcription entrypoints | +| `src/pipeline.rs` | Parallel task coordinator using rayon — runs frame extraction and scene detection concurrently | +| `src/scene.rs` | Scene change detection using perceptual hashing (pHash) | +| `src/transcribe.rs` | Whisper-based audio transcription (feature-gated: `transcription`) | +| `src/video.rs` | `VideoConfig` and FFmpeg CLI invocation for frame extraction | +| `src/error.rs` | `PerceptionError` and `Result` type alias | + +## Subdirectories +| Directory | Purpose | +|-----------|---------| +| `src/` | All Rust source (see `src/AGENTS.md`) | + +## For AI Agents + +### Working In This Directory +- Requires `ffmpeg` CLI available in PATH at runtime for frame extraction. +- `transcription` feature adds Whisper model loading; gated to avoid mandatory large model downloads. +- `cuda` feature requires CUDA toolkit — only used with `transcription`. +- Default build has no external model dependencies. + +### Testing Requirements +- `cargo test -p lucid-perception` — unit tests +- Transcription tests require `--features transcription` and a Whisper model present. + +## Dependencies + +### Internal +- Consumed by `crates/lucid-perception-napi` + +### External +- FFmpeg CLI (runtime dependency — spawned as child process) +- `rayon` (parallelism), `thiserror` (error types) +- Optional: Whisper model, CUDA toolkit + + diff --git a/crates/lucid-perception/CLAUDE.md b/crates/lucid-perception/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-perception/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-perception/GEMINI.md b/crates/lucid-perception/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-perception/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-perception/src/AGENTS.md b/crates/lucid-perception/src/AGENTS.md new file mode 100644 index 0000000..b6239db --- /dev/null +++ b/crates/lucid-perception/src/AGENTS.md @@ -0,0 +1,26 @@ + + + +# lucid-perception/src + +## Purpose +Video perception pipeline implementation: FFmpeg-based frame extraction, perceptual hashing for scene detection, and optional Whisper audio transcription. + +## Key Files +| File | Description | +|------|-------------| +| `lib.rs` | Public API: `extract_frames`, `detect_scenes`, transcription entrypoints | +| `pipeline.rs` | Parallel task coordinator — runs frame extraction and scene detection concurrently via rayon | +| `scene.rs` | Perceptual hashing (pHash) for scene change detection | +| `transcribe.rs` | Whisper integration for audio transcription (feature-gated: `transcription`) | +| `video.rs` | `VideoConfig` and FFmpeg CLI invocation for frame extraction | +| `error.rs` | `PerceptionError` and `Result` type alias | + +## For AI Agents + +### Working In This Directory +- FFmpeg is spawned as a child process — verify PATH availability in test environments. +- `transcription` feature adds Whisper model loading; keep it gated to avoid large mandatory downloads. +- `pipeline.rs` uses rayon for parallelism — frame extraction and scene detection run concurrently. + + diff --git a/crates/lucid-perception/src/CLAUDE.md b/crates/lucid-perception/src/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-perception/src/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/crates/lucid-perception/src/GEMINI.md b/crates/lucid-perception/src/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/crates/lucid-perception/src/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/AGENTS.md b/packages/AGENTS.md new file mode 100644 index 0000000..4b7975f --- /dev/null +++ b/packages/AGENTS.md @@ -0,0 +1,25 @@ + + + +# packages + +## Purpose +TypeScript/Bun workspace packages. The MCP server (`lucid-server`) is the user-facing entry point; it depends on pre-built native binaries distributed as separate packages (`lucid-native`, `lucid-perception`) to avoid requiring users to compile Rust. + +## Subdirectories +| Directory | Purpose | +|-----------|---------| +| `lucid-server/` | MCP server: storage, retrieval, embeddings, consolidation, episodic memory (see `lucid-server/AGENTS.md`) | +| `lucid-native/` | Pre-built `.node` binaries for lucid-core N-API, one per platform (see `lucid-native/AGENTS.md`) | +| `lucid-perception/` | Pre-built `.node` binaries for lucid-perception N-API, one per platform (see `lucid-perception/AGENTS.md`) | + +## For AI Agents + +### Working In This Directory +- All packages are Bun workspace members (declared in root `package.json` `workspaces`). +- Run tests with `bun --filter '*' test` or per-package with `bun test` inside the package directory. +- Named exports only — no default exports. +- `lucid-native` and `lucid-perception` are distribution packages — `.node` files are built by CI and committed; do not rebuild locally unless explicitly required. +- `lucid-server` depends on `lucid-native` and `lucid-perception` via `file:` workspace references. + + diff --git a/packages/CLAUDE.md b/packages/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/GEMINI.md b/packages/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-native/AGENTS.md b/packages/lucid-native/AGENTS.md new file mode 100644 index 0000000..18cf3de --- /dev/null +++ b/packages/lucid-native/AGENTS.md @@ -0,0 +1,28 @@ + + + +# lucid-native + +## Purpose +Distribution package for pre-built `lucid-core` N-API binaries. Ships one `.node` file per supported platform (darwin-arm64, linux-arm64-gnu, linux-x64-gnu, win32-x64-msvc). Users install this package to avoid compiling Rust. Binaries built by CI via `build-native.yml`. + +## Key Files +| File | Description | +|------|-------------| +| `package.json` | Package manifest: `@lucid-memory/native` | +| `index.js` | Entry point — selects and loads the correct `.node` binary for the current platform | +| `index.d.ts` | TypeScript type declarations for the native module API | +| `lucid-native.darwin-arm64.node` | Pre-built binary for macOS ARM64 | +| `lucid-native.linux-arm64-gnu.node` | Pre-built binary for Linux ARM64 | +| `lucid-native.linux-x64-gnu.node` | Pre-built binary for Linux x86-64 | +| `lucid-native.win32-x64-msvc.node` | Pre-built binary for Windows x86-64 | + +## For AI Agents + +### Working In This Directory +- Do not manually edit `.node` files — they are build artifacts from `crates/lucid-napi`. +- To rebuild: `napi build --release` in `crates/lucid-napi`, then copy output binaries here. +- CI builds all platforms via `build-native.yml` and commits the binaries — prefer that path. +- `index.js` selects the binary at runtime using `process.platform` + `process.arch`. + + diff --git a/packages/lucid-native/CLAUDE.md b/packages/lucid-native/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-native/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-native/GEMINI.md b/packages/lucid-native/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-native/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-perception/AGENTS.md b/packages/lucid-perception/AGENTS.md new file mode 100644 index 0000000..105e662 --- /dev/null +++ b/packages/lucid-perception/AGENTS.md @@ -0,0 +1,27 @@ + + + +# packages/lucid-perception + +## Purpose +Distribution package for pre-built `lucid-perception` N-API binaries. Ships platform-specific `.node` files (darwin-arm64, darwin-x64, linux-x64-gnu, win32-x64-msvc). Built by CI; users install to avoid Rust compilation. + +## Key Files +| File | Description | +|------|-------------| +| `package.json` | Package manifest: `@lucid-memory/perception` | +| `index.js` | Entry point — loads the correct `.node` binary for the current platform | +| `index.d.ts` | TypeScript type declarations for the perception module API | +| `lucid-perception.darwin-arm64.node` | Pre-built binary for macOS ARM64 | +| `lucid-perception.darwin-x64.node` | Pre-built binary for macOS x86-64 | +| `lucid-perception.linux-x64-gnu.node` | Pre-built binary for Linux x86-64 | +| `lucid-perception.win32-x64-msvc.node` | Pre-built binary for Windows x86-64 | + +## For AI Agents + +### Working In This Directory +- Do not manually edit `.node` files — built artifacts from `crates/lucid-perception-napi`. +- To rebuild: `napi build --release` in `crates/lucid-perception-napi`, then copy here. +- CI builds all platforms via `build-native.yml` and commits the binaries. + + diff --git a/packages/lucid-perception/CLAUDE.md b/packages/lucid-perception/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-perception/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-perception/GEMINI.md b/packages/lucid-perception/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-perception/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-server/AGENTS.md b/packages/lucid-server/AGENTS.md new file mode 100644 index 0000000..1ce878e --- /dev/null +++ b/packages/lucid-server/AGENTS.md @@ -0,0 +1,65 @@ + + + +# lucid-server + +## Purpose +MCP server providing persistent AI memory via the Model Context Protocol. Exposes memory tools (store, query, context, forget, consolidation, episodic, location, video) over stdio transport. Entry point for Claude Code, OpenCode, and Codex integrations. Data stored in `~/.lucid/`. + +## Key Files +| File | Description | +|------|-------------| +| `package.json` | Package manifest; bin entries `lucid-server` and `lucid` | +| `src/server.ts` | MCP server entrypoint — registers all tools, starts stdio transport | +| `src/index.ts` | Public library re-exports (programmatic API surface) | +| `src/storage.ts` | SQLite storage layer: memories, associations, episodes, consolidation state | +| `src/retrieval.ts` | `LucidRetrieval` — orchestrates Rust native retrieval with TS fallback | +| `src/embeddings.ts` | `EmbeddingClient` — auto-detects provider (local ONNX / OpenAI-compatible endpoint) | +| `src/config.ts` | Cognitive parameter config: activation, encoding, working memory, consolidation | +| `src/consolidation.ts` | `ConsolidationEngine` — background loop: strengthen recent, decay stale, prune weak | +| `src/gist.ts` | Gist extraction: distills verbatim memory traces to compressed semantic essence | +| `src/episodic-memory.ts` | `EpisodicMemory` — temporal episode boundary detection and sequence reconstruction | +| `src/video.ts` | Video memory: frame extraction, visual storage, scene-based retrieval | +| `src/cli.ts` | `lucid` CLI for diagnostics, memory inspection, config management | + +## Subdirectories +| Directory | Purpose | +|-----------|---------| +| `src/` | All TypeScript source and tests (see `src/AGENTS.md`) | +| `bin/` | Platform wrapper scripts that launch the MCP server process (see `bin/AGENTS.md`) | +| `hooks/` | Claude Code and Codex hook scripts fired on AI lifecycle events (see `hooks/AGENTS.md`) | +| `plugins/` | Third-party client adapter plugins (e.g. OpenCode) (see `plugins/AGENTS.md`) | +| `scripts/` | Package-level install and setup scripts (see `scripts/AGENTS.md`) | + +## For AI Agents + +### Working In This Directory +- All MCP tools are registered in `src/server.ts`. Adding a tool: zod schema → handler → `server.tool(name, schema, handler)`. +- Database at `~/.lucid/` — shared by default; `LUCID_CLIENT` env selects per-client or profile mode. +- Embedding provider auto-detected: local ONNX model → OpenAI-compatible endpoint → fallback. +- Named exports only; `src/index.ts` is the public library surface. +- Storage changes require a migration in `storage.ts` — version schema incrementally. + +### Testing Requirements +- `bun test` runs all `*.test.ts` files. +- Integration test `location-rust-integration.test.ts` requires native binary present. +- All 5 completion gates apply — see root `CLAUDE.md`. + +### Common Patterns +- `LucidStorage` is the single DB access point — all modules receive it as a constructor argument. +- `LucidRetrieval` wraps the Rust native module for the hot retrieval path. +- Consolidation runs async in background — never await it on the MCP request hot path. +- All embedding vectors are L2-normalized before storage; use `normalize()` from `embeddings.ts`. + +## Dependencies + +### Internal +- `@lucid-memory/native` (lucid-core N-API bindings) +- `@lucid-memory/perception` (lucid-perception N-API bindings) + +### External +- `@modelcontextprotocol/sdk` (MCP server + stdio transport) +- `zod` (tool schema validation) +- SQLite via Bun's built-in `bun:sqlite` + + diff --git a/packages/lucid-server/CLAUDE.md b/packages/lucid-server/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-server/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-server/GEMINI.md b/packages/lucid-server/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-server/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-server/bin/AGENTS.md b/packages/lucid-server/bin/AGENTS.md new file mode 100644 index 0000000..d44f172 --- /dev/null +++ b/packages/lucid-server/bin/AGENTS.md @@ -0,0 +1,21 @@ + + + +# lucid-server/bin + +## Purpose +Platform wrapper scripts that launch the lucid-server MCP process. Used by Claude Code and other clients to invoke the server with the correct environment. + +## Key Files +| File | Description | +|------|-------------| +| `lucid-server-wrapper.sh` | Bash wrapper — sets env vars and execs `bun run src/server.ts` | +| `lucid-server-wrapper.ps1` | PowerShell equivalent for Windows | + +## For AI Agents + +### Working In This Directory +- Wrappers set `LUCID_CLIENT` and other env vars before delegating to the server. +- Changes here affect how Claude Code and Codex launch the server — validate with `scripts/test-mcp.sh`. + + diff --git a/packages/lucid-server/bin/CLAUDE.md b/packages/lucid-server/bin/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-server/bin/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-server/bin/GEMINI.md b/packages/lucid-server/bin/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-server/bin/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-server/hooks/AGENTS.md b/packages/lucid-server/hooks/AGENTS.md new file mode 100644 index 0000000..f3ff969 --- /dev/null +++ b/packages/lucid-server/hooks/AGENTS.md @@ -0,0 +1,23 @@ + + + +# lucid-server/hooks + +## Purpose +Claude Code and Codex hook scripts injected into AI agent sessions. Scripts fire on AI lifecycle events (e.g. `UserPromptSubmit`) to trigger memory retrieval and inject context into the agent's context window. + +## Key Files +| File | Description | +|------|-------------| +| `user-prompt-submit.sh` | Bash hook — fires on `UserPromptSubmit`; calls `memory_context` MCP tool and injects result | +| `user-prompt-submit.ps1` | PowerShell equivalent for Windows | +| `codex-notify.sh` | Bash hook for OpenAI Codex — notifies lucid-server of prompt events | + +## For AI Agents + +### Working In This Directory +- Hooks must be fast — they block the AI agent session until they return. +- `user-prompt-submit.sh` injects retrieved memory context into the session via stdout. +- Do not add heavy computation here; all work should delegate to the MCP server. + + diff --git a/packages/lucid-server/hooks/CLAUDE.md b/packages/lucid-server/hooks/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-server/hooks/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-server/hooks/GEMINI.md b/packages/lucid-server/hooks/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-server/hooks/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-server/plugins/AGENTS.md b/packages/lucid-server/plugins/AGENTS.md new file mode 100644 index 0000000..c4ba3e3 --- /dev/null +++ b/packages/lucid-server/plugins/AGENTS.md @@ -0,0 +1,21 @@ + + + +# lucid-server/plugins + +## Purpose +Third-party client adapter plugins. Each plugin adapts Lucid Memory MCP tools for a specific AI client that requires a custom integration format beyond the standard MCP stdio transport. + +## Key Files +| File | Description | +|------|-------------| +| `opencode-lucid-memory.ts` | OpenCode plugin — exposes lucid-memory tools in OpenCode's plugin format | + +## For AI Agents + +### Working In This Directory +- Plugins re-export lucid-server tool logic in client-specific formats. +- When adding a new client integration, add a plugin file here rather than modifying `server.ts`. +- Plugin files must use named exports only. + + diff --git a/packages/lucid-server/plugins/CLAUDE.md b/packages/lucid-server/plugins/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-server/plugins/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-server/plugins/GEMINI.md b/packages/lucid-server/plugins/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-server/plugins/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-server/scripts/AGENTS.md b/packages/lucid-server/scripts/AGENTS.md new file mode 100644 index 0000000..6e50517 --- /dev/null +++ b/packages/lucid-server/scripts/AGENTS.md @@ -0,0 +1,20 @@ + + + +# lucid-server/scripts + +## Purpose +Package-level installation and setup scripts for lucid-server. + +## Key Files +| File | Description | +|------|-------------| +| `install.sh` | Post-install script — configures lucid-server in Claude Code MCP settings at `~/.claude/` | + +## For AI Agents + +### Working In This Directory +- `install.sh` is invoked after package installation to register the MCP server with Claude Code. +- Modifies client config files under `~/.claude/` or equivalent — test carefully to avoid corrupting user config. + + diff --git a/packages/lucid-server/scripts/CLAUDE.md b/packages/lucid-server/scripts/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-server/scripts/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-server/scripts/GEMINI.md b/packages/lucid-server/scripts/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-server/scripts/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-server/src/AGENTS.md b/packages/lucid-server/src/AGENTS.md new file mode 100644 index 0000000..36613ab --- /dev/null +++ b/packages/lucid-server/src/AGENTS.md @@ -0,0 +1,50 @@ + + + +# lucid-server/src + +## Purpose +TypeScript source for the Lucid Memory MCP server. Implements memory storage, retrieval, embedding, consolidation, episodic memory, gist extraction, video memory, and location tracking — all exposed as MCP tools. + +## Key Files +| File | Description | +|------|-------------| +| `server.ts` | MCP server entrypoint — all tools registered here, stdio transport, multi-client config | +| `index.ts` | Public library re-exports (programmatic API surface) | +| `storage.ts` | `LucidStorage` — SQLite schema, migrations, and all DB operations | +| `retrieval.ts` | `LucidRetrieval` — orchestrates Rust native retrieval with TS fallback | +| `embeddings.ts` | `EmbeddingClient` — auto-detects provider, computes and normalizes embeddings | +| `config.ts` | Cognitive config types: `CognitiveConfig`, `ActivationConfig`, `ConsolidationConfig`, etc. | +| `consolidation.ts` | `ConsolidationEngine` — background loop: strengthen, decay, prune, manage visual lifecycle | +| `gist.ts` | Gist extraction: distills verbatim memory traces to compressed semantic essence | +| `episodic-memory.ts` | `EpisodicMemory` — episode boundary detection and temporal sequence reconstruction | +| `video.ts` | Video memory: frame extraction, visual storage, scene-based retrieval | +| `cli.ts` | `lucid` CLI — diagnostics, memory inspection, config management | + +## Test Files +| File | Description | +|------|-------------| +| `storage.test.ts` | Storage CRUD, migrations, association graph | +| `consolidation.test.ts` | Consolidation engine: strengthen/decay/prune logic | +| `episodic-memory.test.ts` | Episode boundary detection and reconstruction | +| `embedding-migration.test.ts` | Embedding provider migration correctness | +| `gist.test.ts` | Gist extraction quality and idempotency | +| `temporal-retrieval.test.ts` | Temporal decay and recency scoring | +| `association-index.test.ts` | Association graph index operations | +| `location-rust-integration.test.ts` | Location tracking via Rust native module (requires binary) | + +## For AI Agents + +### Working In This Directory +- `LucidStorage` is the single DB access object — all modules receive it as a constructor arg. +- MCP tool registration lives entirely in `server.ts`; do not scatter it across files. +- `EmbeddingClient` is shared — instantiate once in `server.ts` and inject into dependents. +- Consolidation runs async in background — never await it on the MCP request hot path. +- Named exports only, no default exports. +- All embedding vectors are L2-normalized before storage; use `normalize()` from `embeddings.ts`. + +### Common Patterns +- New MCP tool: add zod schema → handler function → `server.tool(name, schema, handler)` in `server.ts`. +- Storage schema changes require a versioned migration in `storage.ts`. + + diff --git a/packages/lucid-server/src/CLAUDE.md b/packages/lucid-server/src/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-server/src/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-server/src/GEMINI.md b/packages/lucid-server/src/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/packages/lucid-server/src/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/packages/lucid-server/src/cli.ts b/packages/lucid-server/src/cli.ts index 3edd602..24898e4 100644 --- a/packages/lucid-server/src/cli.ts +++ b/packages/lucid-server/src/cli.ts @@ -427,10 +427,26 @@ Examples: embeddingStatus = embeddingDiagnostics.ollamaError ?? "not available" } } else if (embeddingConfig?.provider === "openai") { - embeddingStatus = embeddingConfig.openaiApiKey - ? "ready (OpenAI API)" - : "no API key" - isEmbeddingHealthy = !!embeddingConfig.openaiApiKey + if (embeddingConfig.openaiBaseUrl) { + try { + const probe = await fetch(`${embeddingConfig.openaiBaseUrl}/models`, { + signal: AbortSignal.timeout(3000), + }) + if (probe.ok) { + embeddingStatus = `ready (${embeddingConfig.openaiBaseUrl})` + isEmbeddingHealthy = true + } else { + embeddingStatus = `unreachable (${embeddingConfig.openaiBaseUrl}) — HTTP ${probe.status}` + } + } catch { + embeddingStatus = `unreachable (${embeddingConfig.openaiBaseUrl})` + } + } else { + embeddingStatus = embeddingConfig.openaiApiKey + ? "ready (OpenAI API)" + : "no API key" + isEmbeddingHealthy = !!embeddingConfig.openaiApiKey + } } // Database status diff --git a/packages/lucid-server/src/embeddings.ts b/packages/lucid-server/src/embeddings.ts index 8b81603..455aa5b 100644 --- a/packages/lucid-server/src/embeddings.ts +++ b/packages/lucid-server/src/embeddings.ts @@ -92,6 +92,7 @@ export interface EmbeddingConfig { model?: string ollamaHost?: string openaiApiKey?: string + openaiBaseUrl?: string } export interface EmbeddingResult { @@ -244,7 +245,12 @@ export class EmbeddingClient { const response = await fetch(`${host}/api/tags`) return response.ok } - // OpenAI: just check if API key exists + if (this.config.openaiBaseUrl) { + const response = await fetch(`${this.config.openaiBaseUrl}/models`, { + signal: AbortSignal.timeout(3000), + }) + return response.ok + } return !!this.config.openaiApiKey } catch { return false @@ -360,19 +366,22 @@ export class EmbeddingClient { } private async embedOpenAIBatch(texts: string[]): Promise { + const baseUrl = this.config.openaiBaseUrl ?? "https://api.openai.com/v1" const apiKey = this.config.openaiApiKey - if (!apiKey) { + + if (!apiKey && !this.config.openaiBaseUrl) { throw new Error("OpenAI API key required") } const model = this.config.model ?? defaultOpenaiModel + const headers: Record = { "Content-Type": "application/json" } + if (apiKey) { + headers.Authorization = `Bearer ${apiKey}` + } - const response = await fetch("https://api.openai.com/v1/embeddings", { + const response = await fetch(`${baseUrl}/embeddings`, { method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: `Bearer ${apiKey}`, - }, + headers, body: JSON.stringify({ model, input: texts, @@ -413,6 +422,18 @@ export async function detectProvider(): Promise { openaiAvailable: false, } + // 0. Explicit local embedding endpoint (LM Studio, Ollama OpenAI-compat, vLLM, etc.) + // biome-ignore lint/style/noProcessEnv: Config detection requires environment access + const embeddingUrl = process.env.LUCID_EMBEDDING_URL + if (embeddingUrl) { + // biome-ignore lint/style/noProcessEnv: Config detection requires environment access + const embeddingModel = process.env.LUCID_EMBEDDING_MODEL + return { + config: { provider: "openai", openaiBaseUrl: embeddingUrl, model: embeddingModel }, + diagnostics, + } + } + // 1. Try native in-process embeddings (zero deps, best UX) if (!nativeEmbedding) { diagnostics.nativeStatus = "module_unavailable" diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md new file mode 100644 index 0000000..c75aaf4 --- /dev/null +++ b/scripts/AGENTS.md @@ -0,0 +1,23 @@ + + + +# scripts + +## Purpose +Build, install validation, and release automation scripts used in CI and locally. + +## Key Files +| File | Description | +|------|-------------| +| `lint-installers.sh` | Validates `install.sh` and `install.ps1` for shell linting issues | +| `test-install.sh` | End-to-end install script smoke test — runs the installer and verifies the server starts | +| `test-mcp.sh` | MCP server smoke test — starts the server and verifies tool responses via stdio | + +## For AI Agents + +### Working In This Directory +- `test-mcp.sh` requires a running lucid-server; exercises the MCP tool interface end-to-end. +- Run these in CI via `.github/workflows/ci.yml` — check that workflow before modifying script interfaces. +- Script changes should be validated locally before merging (`bash -n script.sh` for syntax check). + + diff --git a/scripts/CLAUDE.md b/scripts/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/scripts/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/scripts/GEMINI.md b/scripts/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/scripts/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file