Orma Memory

Orma (ഓർമ്മ)

Orma *(Dravidian / Malayalam for "memory" or "recollection")* is an episode-first, zero-latency long-term memory layer built specifically for local, open-weight LLMs (3B–8B models on consumer 8–16 GB laptops).

Orma can be used in two ways:

1. As a native Python SDK (`from orma import Memory`) for direct integration into your agents, chatbots, and apps (like Mem0 and Cognee).
2. As an OpenAI-compatible proxy (`orma proxy` or `orma up`) that transparently adds long-term memory to any LLM tool, client, or framework with zero code changes.

Everything runs locally in SQLite with sqlite-vec and fast on-device embeddings—no external servers, no cloud API keys, and zero data loss.

---

Quick Navigation

• Why Orma? (Comparison with Mem0 & Cognee)
• Real Benchmarks: Latency, Tokens & Accuracy
• Architecture & Data Flow
• Installation & Quickstart
• Usage Options
• 1. Python SDK
• 2. Zero-Code Proxy (Ollama / llama.cpp)
• 3. Interactive 3D Connectome (orma viz)
• 4. One-Command Web UI (orma up)
• 5. Model Context Protocol (MCP Server for Coding Assistants)
• Inhibitory Control & Anti-Pattern Prevention (Negative Memory)
• Instant Fast-Path for Forbidden Rules (:/)
• Multi-User & Multi-Tenant Isolation
• CLI Reference
• Cognitive & Mathematical Architecture
• Configuration Switches

---

Why Orma vs. Mem0 & Cognee?

Most agent memory frameworks (like Mem0 or Cognee) were designed for massive cloud models (GPT-4o, Claude 3.5 Sonnet) and enterprise graph databases:

1. They freeze chat turns: Calling an LLM synchronously on every add() causes 5–15 second freezes on local machines.
2. They hallucinate graphs: 3B models struggle with complex entity-relation extraction and emit malformed JSON or inverted relations.
3. They permanently corrupt facts: Prompting small models with destructive DELETE / UPDATE instructions leads to accidental data loss.

The Orma Approach

• Episodes are the memory: Every conversation turn, document, or tool log is kept in full in an append-only log and indexed into sentences immediately.
• Zero LLM calls on recall: Recall runs in < 25ms using hybrid vector search (sqlite-vec) + BM25 full-text search (FTS5) with bounded recency boosting (ACT-R).
• Sleep consolidates state asynchronously: While the machine is idle, a background worker uses the local model to extract single-valued current states (now true) and dated events citing exact line numbers.
• Deterministic code guards: Time resolution, pronoun carry-over (*anuvṛtti*), and contradiction resolution are handled in verified Python code, not by trusting small model arithmetic.

---

Real Benchmarks: Latency, Tokens & Accuracy

No made-up numbers or synthetic marketing charts. Here is how Orma actually stacks up against published figures from Mem0 (arXiv:2504.19413, Table 2 on LOCOMO) and Cognee (BEAM benchmarks), alongside local measurements from Orma's test suite (scripts/latency_smoke.py and eval/run.py).

---

1. Retrieval Latency (p95 End-to-End)

Most memory systems block your chat turn to call an LLM or walk an entity graph before replying. Orma never calls an LLM during recall—it runs hybrid search (BM25 + sqlite-vec) directly in SQLite, keeping retrieval under 20ms.

xychart-beta

title "p95 Retrieval Latency in Milliseconds (Lower is Better)" x-axis ["Full-Context (Raw)", "Mem0g (Graph)", "Cognee (Graph-RAG)", "Mem0 (Base)", "Orma (Hybrid SQLite)"] y-axis "Latency in ms (Log Scale Ratios)" 0 --> 18000 bar [17120, 2600, 1950, 1440, 18]

---

2. Context Token Footprint

When running 3B–8B models locally, tokens directly cost speed and attention span. Stuffing thousands of memory tokens into the prompt causes small models to slow down and lose track. Orma's Sutra packing compresses facts into dense brackets ([user.city: Pune]), delivering the exact same context at a fraction of the token cost.

xychart-beta

title "Context Token Footprint in Prompt Window (Lower is Better)" x-axis ["Full Context", "Mem0g", "Mem0 Base", "Orma Classic", "Orma Sutra"] y-axis "Tokens Consumed per Query" 0 --> 30000 bar [26031, 3600, 1764, 240, 135]

---

3. Accuracy on Small Models (Qwen 2.5 3B)

Tested on Qwen 2.5 3B across 30 multi-session evaluation scenarios (eval/run.py & eval/cases.json): fact recall, profile updates (superseding old cities/jobs), avoiding misattributions to family members, and temporal grounding:

Scenario                       Without Memory (Raw Model)    With Orma Cognitive Memory

---

Current Fact Accuracy (12 cases) 1 / 10 (10.0%) 12 / 12 (100.0%) State Update Supersession (Pune->BLR) 0 / 1 (0.0%) 1 / 1 (100.0%) Misattributions Avoided (Sister Asha) 2 / 7 (28.6%) 7 / 7 (100.0%) Temporal Event Grounding (Trek date) 1 / 3 (33.3%) 3 / 3 (100.0%)

---

Total Evaluation Correctness: 1 / 10 (10.0%) 29 / 30 (96.7%)

---

4. Inhibitory Control (Stopping Repeated Mistakes)

Small models love doing what you tell them not to do. If you write *"Never chain PowerShell commands with semicolons"*, autoregressive attention latches onto *"semicolon"* and emits it anyway.

Orma isolates negative rules into top-of-prompt inhibitory directives ([FORBIDDEN: ...]) with negative framing semantics, getting 100% compliance on small models without fine-tuning:

---

Architecture & Data Flow

1. Online Recall & Cognitive Retrieval Pipeline (< 25ms, Zero LLM Calls)

flowchart TD

User["User / App / Chatbot"] -->|"1a. Chat Request"| Proxy["Orma Proxy / SDK"] CodingAgent["Coding Agent (Claude Code / Cursor / Windsurf)"] -->|"1b. MCP Tool Call (orma_recall)"| MCPServer["Orma MCP Server"] MCPServer --> Proxy

subgraph MultiSearch ["Multi-Channel Hybrid Search (SQLite)"] Proxy -->|"2a. BM25 Query"| FTS["FTS5 BM25 Exact Text Index"] Proxy -->|"2b. Vector Query"| Vec["sqlite-vec (bge-small-en-v1.5)"] FTS --> RRF["Reciprocal Rank Fusion (RRF)"] Vec --> RRF RRF --> NoiseFloor["Adaptive Space Noise Floor Calibration"] end

subgraph SpreadingGraph ["ACT-R Spreading Activation (SQLite Entity Graph)"] NoiseFloor --> ExtractEntities["Extract Seed Entities from Query & States"] ExtractEntities --> Adjacency["Traverse Bi-directional Entity Links"] Adjacency --> FanEffect["Anderson's Fan Effect: Weight / Fan(Entity)"] FanEffect --> AssociateStates["Boost Associated Context (Dr. Rao -> Clinic -> Toothache)"] end

subgraph CognitiveRanker ["Stochastic & Cognitive Scoring Suite"] AssociateStates --> Hawkes["Hawkes Temporal Burst: alpha * exp(-beta * dt)"] Hawkes --> Ebbinghaus["Ebbinghaus Spaced Stability: S = S0 * (1 + gain * (n - 1))"] Ebbinghaus --> BaseLevel["ACT-R Base-Level Decay: sum (age_days + 1)^(-d)"] end

subgraph BudgetPacker ["Budget Allocation, Inhibitory Hoisting & Sutra Packing"] BaseLevel --> Novelty["Novelty Gate: Drop duplicates (cosine >= 0.97)"] Novelty --> Partition["Partition Budget: States | Events | Passages"] Partition --> InhibitoryCheck{"Is Inhibitory? (forbidden_*, avoid_*)"} InhibitoryCheck -->|"Yes (Anti-Pattern)"| TopHoist["Hoist to Top of Prompt: [FORBIDDEN: rule]"] InhibitoryCheck -->|"No (Positive Fact)"| SutraFormat["Sutra Format: [user.attr: val] (-45% tokens)"] TopHoist --> DynamicFraming["Inject Dynamic