{"_id":"@alltheright121/ulma","_rev":"2-b6e3ecc4e81da5cd5ef1d1adc1636116","name":"@alltheright121/ulma","dist-tags":{"latest":"1.2.0"},"versions":{"1.1.3":{"name":"@alltheright121/ulma","version":"1.1.3","keywords":["ulma","opencode","plugin","rag","memory","lancedb"],"license":"MIT","_id":"@alltheright121/ulma@1.1.3","maintainers":[{"name":"alltheright121","email":"alltheright121@gmail.com"}],"homepage":"https://github.com/drpr/alex/tree/main/ulma#readme","bugs":{"url":"https://github.com/drpr/alex/issues"},"bin":{"ulma":"bin/ulma.js"},"dist":{"shasum":"f7c72819697a8b1ffffc7a16d1a0fe56407cf7c5","tarball":"https://registry.npmjs.org/@alltheright121/ulma/-/ulma-1.1.3.tgz","fileCount":10,"integrity":"sha512-63ll9Hbu8fK03/rnEfpHLXhnHMPh+FiUZtic8PrNn4gHA6T1KIg3VmRa5alkRp/R7+elO5cD1fTDq4WPz0DPgg==","signatures":[{"sig":"MEYCIQDmZn16A2k9Z5RUr5lqVlmEmZ0FkFlVgopw7EXmzTr8JQIhAOLDbpuv4INCYDWVqxHPSMKsQbxHSgjBbDiFHNzG1d2b","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":79055},"main":"plugin.mjs","type":"module","gitHead":"4d4368537b839202e1102be46c2cbe0fddbeb682","_npmUser":{"name":"alltheright121","email":"alltheright121@gmail.com"},"repository":{"url":"git+https://github.com/drpr/alex.git","type":"git","directory":"ulma"},"_npmVersion":"10.8.2","description":"Universal LLM Memory Architecture (ULMA) plugin for OpenCode with project/session isolation","directories":{},"_nodeVersion":"20.20.0","dependencies":{"glob":"^10.3.10","chokidar":"^3.5.3","pdf-parse":"^1.1.1","tesseract.js":"^4.0.2","@lancedb/lancedb":"0.13.0","onnxruntime-node":"^1.23.2","@opencode-ai/plugin":"^1.1.37","@xenova/transformers":"^2.17.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/ulma_1.1.3_1770475453838_0.4104037223427419","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@alltheright121/ulma","version":"1.2.0","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"},"bugs":{"url":"https://github.com/drpr/alex/issues"},"homepage":"https://github.com/drpr/alex/tree/main/ulma#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@1.2.0","gitHead":"f5a77111aaf87e7a021aeb492c47e8b379be4d89","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-61n8I3xTLzeiFnLyaoHIUD5ZmLNrDKqQvv3USO4CGKnU3uGnfYLzNB8M5YYFC/z7nT/d7kI880NkZEDeXgnT5w==","shasum":"eee9fbfb37f45d8e0e63cbfe0f58c8dd13827e2a","tarball":"https://registry.npmjs.org/@alltheright121/ulma/-/ulma-1.2.0.tgz","fileCount":13,"unpackedSize":98730,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDg5vydWt0LvTZ82Bou4OZqYUUnOPf3uRuBAZHbO4TrMAiEAgLvCj9OzhWoXMJNHCqS9voeVnHnrUXtrJ7ltPeUwrBc="}]},"_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_1.2.0_1770646306889_0.9052884338876492"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-07T14:44:13.752Z","modified":"2026-02-09T14:11:47.189Z","1.1.3":"2026-02-07T14:44:13.991Z","1.2.0":"2026-02-09T14:11:47.068Z"},"bugs":{"url":"https://github.com/drpr/alex/issues"},"license":"MIT","homepage":"https://github.com/drpr/alex/tree/main/ulma#readme","keywords":["ulma","opencode","plugin","rag","memory","lancedb"],"repository":{"type":"git","url":"git+https://github.com/drpr/alex.git","directory":"ulma"},"description":"Universal LLM Memory Architecture (ULMA) plugin for OpenCode with project/session isolation","maintainers":[{"name":"alltheright121","email":"alltheright121@gmail.com"}],"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.\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.\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- 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\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    \"ulma\"\n  ]\n}\n```\n\n3. Restart your OpenCode session. The plugin will be automatically downloaded and installed.\n\n### Option B: Local Development Install\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\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.\n4. Point your OpenCode config to the absolute path of the `ulma` directory:\n\n```json\n{\n  \"plugin\": [\n    \"/Users/yourname/path/to/alex/ulma\"\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- 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/ulma\n  - GitHub: https://github.com/drpr/alex/tree/main/ulma\n  - In the community directory, search for “ulma” 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"}