{"_id":"@alltheright121/ulma-plugin","name":"@alltheright121/ulma-plugin","dist-tags":{"latest":"1.3.1"},"versions":{"1.3.1":{"name":"@alltheright121/ulma-plugin","version":"1.3.1","description":"Universal LLM Memory Architecture (ULMA) plugin for OpenCode with project/session isolation","main":"plugin.mjs","type":"module","license":"MIT","repository":{"type":"git","url":"git+https://github.com/drpr/alex.git","directory":"ulma-plugin"},"bugs":{"url":"https://github.com/drpr/alex/issues"},"homepage":"https://github.com/drpr/alex/tree/main/ulma-plugin#readme","publishConfig":{"access":"public"},"keywords":["ulma","opencode","plugin","rag","memory","lancedb"],"bin":{"ulma":"bin/ulma.js"},"dependencies":{"@lancedb/lancedb":"0.13.0","@opencode-ai/plugin":"^1.1.37","@xenova/transformers":"^2.17.2","chokidar":"^3.5.3","glob":"^10.3.10","onnxruntime-node":"^1.23.2","pdf-parse":"^1.1.1","tesseract.js":"^4.0.2","tree-sitter-c-sharp":"^0.23.1","web-tree-sitter":"^0.26.5"},"_id":"@alltheright121/ulma-plugin@1.3.1","gitHead":"eb03580e573c77f61b33d883ca648397cd23b81d","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-kQnPp3gI/uoH/mwF5muaFn+2+ToNBzEpkezxYUpfnDTdkcRAkm2b5q1rP6NJsjVxJbfvUWEONzGc+ZJevnl0/A==","shasum":"b80f1afe91f0ddc2ea0e9a3fb68087d25e554fdd","tarball":"https://registry.npmjs.org/@alltheright121/ulma-plugin/-/ulma-plugin-1.3.1.tgz","fileCount":14,"unpackedSize":122579,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAUvn1pY4NZPFFZCXw4IFDFAdNpxOSKIh0BY8XAU/fIhAiEAk+1HaHQxu3mM2gGF29q1hf2/B/diS1B3/c5DZScNil0="}]},"_npmUser":{"name":"alltheright121","email":"alltheright121@gmail.com"},"directories":{},"maintainers":[{"name":"alltheright121","email":"alltheright121@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ulma-plugin_1.3.1_1771506899703_0.7145209443348592"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-19T13:14:59.601Z","1.3.1":"2026-02-19T13:14:59.859Z","modified":"2026-02-19T13:15:00.088Z"},"maintainers":[{"name":"alltheright121","email":"alltheright121@gmail.com"}],"description":"Universal LLM Memory Architecture (ULMA) plugin for OpenCode with project/session isolation","homepage":"https://github.com/drpr/alex/tree/main/ulma-plugin#readme","keywords":["ulma","opencode","plugin","rag","memory","lancedb"],"repository":{"type":"git","url":"git+https://github.com/drpr/alex.git","directory":"ulma-plugin"},"bugs":{"url":"https://github.com/drpr/alex/issues"},"license":"MIT","readme":"# ULMA (Universal LLM Memory Architecture) Plugin\n\nULMA is the **fundamental solution** to the \"Project Amnesia\" problem in AI coding agents. It provides a strictly isolated, local-first memory architecture that guarantees **coding efficiency** and **architectural consistency** across long-term projects.\n\nUnlike generic memory plugins that treat context as a flat list, ULMA understands project boundaries and session lifecycles, ensuring your agent never \"hallucinates\" patterns from other repos or forgets architectural decisions made weeks ago.\n\n## The Core Value: Solving Global Memory Fundamentally\n\nMost AI agents suffer from **Context Drift**: as a project grows, they lose track of established patterns, or worse, bleed context from Project A into Project B. ULMA solves this at the architectural level:\n\n### 1. Agent Efficiency & Zero-Shot Accuracy\n- **Problem:** Agents often waste tokens re-learning your project structure in every session.\n- **Solution:** With persistent, project-hashed memory, ULMA instantly provides the *exact* relevant context (types, utils, patterns) before the agent writes a single line. This drastically reduces \"correction loops\" and makes the agent \"get it right the first time.\"\n\n### 2. Architectural Consistency (The \"Deep Memory\")\n- **Problem:** \"Why did you use `var` here? We switched to `const` last week!\" Agents forget past decisions.\n- **Solution:** By retrieving historical context scoped strictly to the current project, the agent maintains consistent coding styles, variable naming conventions, and architectural patterns throughout the project's lifecycle—whether it's Day 1 or Day 100.\n\n### 3. Absolute Project Isolation (No \"Cross-Talk\")\n- **Problem:** Working on a Rust backend in the morning and a React frontend in the afternoon often confuses agents, leading to \"hallucinated\" imports or syntax.\n- **Solution:** **Hard Directory Hashing**. Vectors for Project A are physically stored in `.ulma/vectors/<hash_A>`. It is mathematically impossible for the agent to access Project B's context while working on Project A. This is not just a filter; it's a **physical firewall** for your context.\n\n---\n\n## Why ULMA: The Definitive Comparison\n\nWhile plugins like `opencode-supermemory` or `opencode-mem` offer memory, they often rely on cloud services or loose tagging. ULMA is built for **Enterprise-Grade Consistency**.\n\n| Feature | ULMA | Cloud Memory Plugins | Generic Local Plugins |\n| :--- | :--- | :--- | :--- |\n| **Global Memory Problem** | **SOLVED (Physical Isolation)** | Mitigated (Tags/Filters) | Unsolved (Flat File) |\n| **Agent Consistency** | **High (Project-Scoped RAG)** | Medium (Global Context Noise) | Low (Session Only) |\n| **Coding Efficiency** | **High (Precise Retrieval)** | Medium (Network Latency) | Low (Limited Context) |\n| **Data Privacy** | **100% Local (LanceDB)** | Cloud Dependent | Local |\n| **Indexing Strategy** | **Incremental & Background** | Full Re-upload | Manual / Sync |\n\n**Verdict:** If you need an agent that \"codes like a senior engineer\" who remembers the project history without getting confused by other projects, **ULMA is the only architectural solution.**\n\n---\n\n## Performance & Benchmarks (v1.2.0)\n\nULMA is built for speed and accuracy in real-world, medium-to-large codebases. Below are the results from our automated benchmark suite running on the **Wasteland** project (~122,000 lines of C#, JS, TS, Rust) on a standard developer machine.\n\n| Metric | Result | Notes |\n| :--- | :--- | :--- |\n| **Indexing Speed** | **~700 lines/s** | Full index (122k lines) in ~173s |\n| **Retrieval Latency** | **170 ms** (Avg) | P99 < 300ms (Hybrid Retrieval) |\n| **Symbol Navigation** | **70.3% Recall** | High accuracy for finding class/method definitions |\n| **Logic Query** | **3.3% Recall** | *Current Limitation*: Semantic queries need future graph analysis |\n\n*Benchmark Environment: MacBook Pro M2, Node.js v18, LanceDB Local.*\n\n**Key Improvements in v1.2:**\n- **Tree-sitter Parsing**: Replaced regex-based chunking with AST-based parsing for C#, Rust, Go, and JS/TS.\n- **Smart Context**: Chunks now include file path and method context for better retrieval.\n- **Optimized Performance**: Query pre-compilation reduced indexing time by 42%.\n\n## Future Roadmap: Advanced Semantic Understanding\n\nWhile ULMA excels at structural symbol navigation (70%+ recall), **Logic-Query** recall remains low (~3.3%). This is a known semantic gap: a user asks \"How is input handled?\", but the code uses terms like `ProcessPacket` or `OnKeyDown`.\n\nTo bridge this gap and achieve \"Senior Engineer\" level understanding, the next phase of ULMA will focus on:\n\n### 1. Code Property Graph (CPG)\nWe will move beyond flat vector retrieval to a graph-based approach. By constructing a lightweight CPG, ULMA will understand:\n- **Call Graphs**: \"Who calls `ProcessPacket`?\"\n- **Data Flow**: \"Where does the `input` variable go?\"\nThis allows the agent to trace logical connections that keyword search misses.\nInitial CPG-lite signals are now integrated for retrieval boosting; full call/data-flow analysis remains pending.\nWe use the lite version to keep indexing latency and memory usage stable in real projects while the full graph pipeline is being validated.\n\n### 2. Query Expansion & HyDE\nUsing LLMs to hallucinate potential code implementations from a natural language query (Hypothetical Document Embeddings).\n- User: \"Handle player input\"\n- Expansion: \"Input.GetKey, OnMouseDown, EventSystem.current\"\nThis expanded query significantly improves vector retrieval accuracy.\nHyDE-lite expansion is now integrated into retrieval; deeper prompt tuning remains pending.\nWe keep HyDE-lite to control noise and cost, and only expand when retrieval benefit is measurable.\n\n### 3. Local-First Deep Embedding\nReplacing generic embedding models with code-specialized models (e.g., fine-tuned BERT for code) that natively understand that `handle input` and `ProcessPacket` are semantically related in a game development context.\n\n## Core Features\n\n## L2 Storage Model\n- Runtime: the plugin maintains in-memory task state for the active session\n- Persistence:\n  - Local JSON Write-Ahead Log: `.ulma/tasks_db.json` (transactional layer)\n  - “Dual-Write” with vector tables (Tasks/Archive) for recoverability\n- Integration:\n  - When integrating with ulma-core service, L2 semantics are event-sourced (L2E/L2S) with files `tasks_events.jsonl` (event log) and `tasks.json` (state view). The plugin aligns to core semantics without redefining them.\n\n- Task tracking and synchronization\n- Memory indexing and retrieval with LanceDB\n- Project‑level vector isolation via hashed project root\n- Session‑level retrieval filters for tasks and history\n- Incremental background indexing\n- Experimental CPG-lite graph signals for retrieval boosting\n- Query expansion (HyDE-lite) for better semantic recall\n\n## Requirements\n\n- OpenCode CLI 1.1.37 (or later)\n- Node.js 18+\n\n## Installation\n\n### Option A: Install from npm (Recommended)\n\n1. Ensure you have the OpenCode CLI installed.\n2. Edit your OpenCode configuration file (usually `~/.config/opencode/config.json` or `%USERPROFILE%\\\\.config\\\\opencode\\\\config.json`):\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"plugin\": [\n    \"@alltheright121/ulma-plugin\"\n  ]\n}\n```\n\n3. Restart your OpenCode session. The plugin will be automatically downloaded and installed.\n\n### Option B: Install from GitHub (Local Path)\n\nIf you want to modify the plugin or use a local version:\n\n1. Clone this repository:\n   ```bash\n   git clone https://github.com/drpr/alex.git\n   cd alex/ulma-plugin\n   ```\n2. Install dependencies:\n   ```bash\n   npm install\n   ```\n3. **Install Language Parsers (Important):**\n   ULMA uses Tree-sitter for advanced code analysis. You must install the WASM parsers before running the plugin.\n   ```bash\n   node scripts/download_parsers.cjs\n   ```\n   *This script will attempt to download parsers from CDN or extract them from `node_modules`.*\n\n4. Build the plugin (if applicable) or ensure `plugin.mjs` is ready.\n\n## Tree-sitter & WASM Configuration\n\nULMA relies on `web-tree-sitter` and language-specific WASM files (e.g., `tree-sitter-c_sharp.wasm`) for structural code understanding. These files are stored in the `parsers/` directory.\n\n### Managing Parsers\n\nThe `scripts/download_parsers.cjs` script is the easiest way to manage these files. It reads configurations from `src/languages/definitions/*.json` and fetches the required WASM files.\n\n**If automatic download fails:**\n1. Install the language package manually: `npm install tree-sitter-c-sharp`\n2. Copy the `.wasm` file from `node_modules/tree-sitter-c-sharp/` to `parsers/tree-sitter-c_sharp.wasm`.\n\n### Supported Languages\nCurrently configured languages (see `src/languages/definitions/`):\n- **C#** (`.cs`): Supports class-based chunking and method symbol extraction.\n- **Rust** (`.rs`): Supports impl/function chunking.\n- **Go** (`.go`): Supports function/method chunking.\n- **JavaScript/TypeScript** (`.js`, `.ts`): Basic support.\n\nTo add more languages, add a JSON definition file and ensure the WASM file is available.\n5. Point your OpenCode config to the absolute path of the `ulma-plugin` directory:\n\n```json\n{\n  \"plugin\": [\n    \"/Users/yourname/path/to/alex/ulma-plugin\"\n  ]\n}\n```\n\n## Configuration\n\nTo customize indexing behavior, create a `.ulma.json` file in the **root of the project you are working on** (not the plugin directory).\n\n```json\n{\n  \"vectorDir\": \".opencode/vectors\",\n  \"include\": [\"**/*.{js,ts,jsx,tsx,py,java,cs,go,rs,md,c,cpp,h}\"],\n  \"exclude\": [\"**/node_modules/**\", \"**/dist/**\", \"**/.git/**\", \"**/.vscode/**\"],\n  \"topK\": 8,\n  \"indexingDebounce\": 1000\n}\n```\n\n### Configuration fields\n\n| Field | Meaning | Recommendation |\n| --- | --- | --- |\n| vectorDir | Vector storage directory | Keep default |\n| include | File patterns to index | Cover primary languages |\n| exclude | File patterns to ignore | Exclude build outputs and dependencies |\n| topK | Max candidates per retrieval | 3–8 |\n\n## Usage\n\n1. Install the plugin and complete configuration  \n2. First run builds the initial index (if missing, the plugin will auto-create the `codebase` table)\n3. Retrieval is scoped by session and project automatically  \n4. Switching projects requires no manual cleanup because isolation is enforced\n\n## Troubleshooting\n\n### v1.3.0 Sync Note\n- Benchmarks relocated under `benchmarks/` (taskset: `benchmarks/wasteland-bench-v2.json`, runner: `benchmarks/ulma-bench-v2.cjs`)\n- Results are saved to `benchmarks/results/ulma-bench-v2.csv`\n- Plugin default config added: `.ulma-plugin.json` (project-level overrides via `.ulma_plugin.json`)\n - GitHub structure: keep only `ulma-plugin/` (legacy `ulma/` not required)\n\n- Bun Error Overlay (macOS)  \n  Use polling-based file watching instead of native fsevents (built-in). If the overlay persists, restart OpenCode and retry.\n- First retrieval returns “Table 'codebase' was not found”  \n  The plugin auto-detects and creates the `codebase` table. Wait for the initial indexing to complete.\n- Version alignment  \n  Ensure your host CLI and plugin interface align to `@opencode-ai/plugin@1.1.37`. Prefer installing via the npm package name to avoid loading stale local path versions.\n\n## Isolation Model\n\n- **Project isolation**: vectors live under `.opencode/vectors/<projectId>`, derived from a hash of the project root\n- **Session isolation**: task and history retrieval are filtered by session ID\n\n## Landscape and References\n\nULMA is designed for developers who demand **absolute context control**.\n\nReferences:\n- OpenCode plugin docs: https://opencode.ai/docs/plugins/\n- Community plugin directory: https://github.com/awesome-opencode/awesome-opencode\n- Find this plugin:\n  - npm: https://www.npmjs.com/package/@alltheright121/ulma-plugin\n  - GitHub: https://github.com/drpr/alex/tree/main/ulma-plugin\n  - In the community directory, search for “ulma-plugin” to locate the listing\n\n## Development\n\n```bash\nnpm install\n```\n\n## Publish\n\n```bash\nnpm publish --access public\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-f6f8cd80da6e17301d08d7663b713335"}