ULMA: Universal LLM Memory Architecture

ULMA is a local-first memory architecture for LLM agents, designed to prevent project amnesia and maintain consistency across long-running workflows. This repository hosts the plugin, the Rust microkernel, and the training data specification for ULMA models.

Repository Layout

• ulma/: OpenCode plugin (Node.js) with indexing and retrieval pipeline.
• ulma-core/: Rust reference implementation (library + gRPC service).
• ulma-model/: Training schemas, samples, de-identification rules, and labeling guidelines.

Memory Model (L1–L4)

• L1 Hot Context: in-memory sliding window for active dialogue.
• L2 Task Anchor: persistent task state and goal retention.
• L3 Warm Index: vector retrieval over code and documents.
• L4 Cold Archive: immutable task archive and audit logs.

Documentation Entry Points

• Plugin usage and configuration: ulma/README.md
• Core overview and navigation: ulma-core/README.md
• Library details: ulma-core/library/README.md
• Service details: ulma-core/service/README.md
• Model data specification: ulma-model

Roadmap: From Engineering to Science

Phase 1: The Robust System (Current)

• Local-first RAG pipeline with LanceDB tables codebase, assets, tasks, archive.
• Incremental indexing via Git diff with full-scan fallback.
• Tree-sitter parsing with regex/line fallback when WASM parsers are missing.
• Assets indexing for PDF/SVG and optional OCR via pdf-parse and tesseract.js.
• Project isolation with .ulma/vectors/<hash>_ts_opt_v3.
• Local task state in .opencode/tasks_db.json.
• Hybrid retrieval (vector + symbolic text match) with RRF re-ranking.
• ulma-core library L1/L2/L3/L4 stack with archival audit and atomic updates.
• ulma-core service gRPC entrypoint with injectable cloud backends (Qdrant/MCP).
• ulma-model schema, samples, de-identification rules, and labeling guidelines for 3B/7B.

Phase 2: Neuro-Symbolic Fusion (Next)

• Code-graph/CPG retrieval in the plugin with ranking integration.
• Use dependency graph signals in retrieval scoring.
• Align plugin and core vocabulary (tables, tiers, task/archive semantics).
• Expand real-project datasets and preference pairs for DPO coverage.

Phase 3: Training & Release (Future)

• Define the 3B/7B training pipeline (CPT + SFT + DPO).
• Establish quantized release flow for deployment targets.

License

See license files in each component directory.