Orma Memory MCP server

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.

Feature	Mem0	Cognee	Orma
Target LLMs	Cloud (GPT-4o)	Cloud (GPT-4o)	Local 3B–8B (Ollama / llama.cpp)
Python SDK	Memory()	cognee.add()	from orma import Memory
Zero-Code Proxy Mode	Paid Cloud / Custom	No	Yes (orma proxy / orma up)
Write Overhead	Synchronous LLM calls (5–15s delay)	Multi-stage graph pipelines	Instant (< 5ms SQLite append)
Recall Overhead	Vector + LLM synthesis	Graph traversal + LLM	Instant (< 25ms hybrid search, 0 LLM calls)
Data Safety	Destructive DELETE / UPDATE	Lossy graph extraction	Lossless append-only logs (rebuild anytime)
Storage Architecture	External Vector DB	Neo4j / NetworkX + Vector	Single embedded SQLite file (~/.orma/memory.db)
Hallucination Protection	Relies on LLM accuracy	Relies on Pydantic output	Line citations + deterministic Python guards

---

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.

Architecture	Retrieval Mechanism	p95 Latency	Relative Speedup	Data Source
Full-Context Baseline	Brute-force historical prompt stuffing	17,120 ms (17.1s)	1.0x (Baseline)	arXiv:2504.19413, Table 2
Mem0g (Graph Variant)	Vector search + Graph traversal	2,600 ms (2.6s)	6.5x faster	arXiv:2504.19413, Table 2
Cognee (Graph-RAG)	Multi-signal vector + entity graph	~1,950 ms (2.0s)	8.8x faster	Cognee BEAM Benchmarks
Mem0 (Base Variant)	Vector semantic lookup + LLM synthesis	1,440 ms (1.4s)	11.9x faster	arXiv:2504.19413, Table 2
Orma (Cognitive Engine)	Zero-LLM Hybrid SQLite (FTS5 + sqlite-vec)	18 ms (0.018s)	951x faster	scripts/latency_smoke.py (2,000 notes)

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.

Memory System	Memory Payload Format	Mean Context Tokens	Token Reduction vs Full Context
Full Context Baseline	Raw multi-session conversation history	~26,031 tokens	0% (Context blowout)
Cognee	Graph context trees & entity relations	~3,650 - 7,000 tokens	~73% - 86%
Mem0g (Graph)	Graph relations + semantic items	~3,600 tokens	86.2%
Mem0 (Base)	Extracted semantic bullet points	~1,764 tokens	93.2%
Orma Classic	Prioritized Markdown sections	~240 tokens (10 facts)	99.1%
Orma Sutra Packing	Dense symbolic brackets: [user.attr: val]	135 tokens (10 facts)	99.5% (-68% vs Mem0 Base)

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:

Approach	Negative Prompt Strategy	Qwen 2.5 3B Compliance	Observed Behavior
Standard User Turn	"Please don't use semicolons"	28% (Fails 7/10)	Generates git add . ; git commit
System Memory Bullet	- user · forbidden: semicolon	45% (Fails 5/10)	Model treats bullet as passive knowledge
Orma Inhibitory Hoisting	[FORBIDDEN: ...] at Top of Prompt + Framing	100% (10/10 Pass)	Generates clean multi-line commands; 0 semicolons

---

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 Negative Framing Semantics"]
        SutraFormat --> DynamicFraming
        DynamicFraming --> MemoryBlock["Construct Prioritized System Memory Block"]
    end

    MemoryBlock -->|"3. Injected Prompt"| Upstream["Local LLM (Ollama / llama.cpp / vLLM)"]
    Upstream -->|"4. Streaming Response"| Proxy
    Proxy -->|"5. Return to User / Agent"| User
    Proxy -.->|"6. Async Non-Blocking Append"| EpisodicLog[("SQLite Append-Only Episodes")]

2. Background Sleep Consolidation & Defeasible Epistemic Logic

flowchart TD
    EpisodicLog[("Pending SQLite Episodes")] -->|"Idle (120s) or Batch Threshold"| Batcher["Episode Batcher (Line IDs [s1, s2, ...])"]
    Batcher --> SleepLLM["Local Sleep Model (Qwen2.5-3B / Llama-3.2-3B)"]
    SleepLLM -->|"Constrained JSON Schema Output"| RawExtraction["Raw States & Events with Line Citations"]

    subgraph DeterministicVerification ["Deterministic Neuro-Symbolic Verification"]
        RawExtraction --> V1["Line Citation Check (Cited sentence exists?)"]
        V1 --> V2["Grounding Engine (Value matches / paraphrases line?)"]
        V2 --> V3["Pronoun & Anaphora Resolution (Anuvṛtti tracking)"]
        V3 --> V4["Calendar & Timezone Anchoring (clock.py)"]
    end

    subgraph InhibitoryAndDefeasibleGate ["Inhibitory & Defeasible Logic Gate"]
        V4 --> ProhibCheck{"Declared Prohibited? (prohibited: true, orma_forbid)"}
        ProhibCheck -->|"Yes (Anti-Pattern / Rule to Avoid)"| ForbiddenPrefix["Namespace Attribute: forbidden_<attr>"]
        ProhibCheck -->|"No (Standard Fact)"| FrameCheck{"Has Schema Condition? (item.condition non-empty)"}
        FrameCheck -->|"No (Categorical Fact)"| Categorical["Supersedes Contradictory Prior State"]
        Categorical --> CloseOld["Mark Old State: active = 0, superseded_by_id = new_id"]
        FrameCheck -->|"Yes (Defeasible Exception)"| Defeasible["Preserve Baseline Truth + Record Conditional Override"]
    end

    CloseOld --> Store[("SQLite State Store & Entity Adjacency Graph")]
    Defeasible --> Store
    ForbiddenPrefix --> Store

---

Installation

pip install orma-ai

Or install from source for development:

git clone https://github.com/wizardwithcodehazard/orma.git
cd orma
pip install -e ".[dev]"
python -m pytest -q  # 218 tests pass locally

---

Usage Option 1: Python SDK (Direct In-Code Integration)

Use the Python SDK to embed Orma directly into your agents, pipelines, or web applications:

from orma import Memory

# 1. Initialize memory (defaults to ~/.orma/memory.db)
mem = Memory(
    upstream="http://localhost:11434/v1",  # Ollama or llama.cpp endpoint
    model="llama3.2:3b"                     # Model for background sleep consolidation
)

# 2. Add memories, documents, or ongoing chat turns
mem.add("I work as a backend engineer and I live in Pune.")
mem.add_file("project_notes.md")

# Record chat interactions
mem.observe(role="user", text="I moved from Pune to Bangalore last week.")
mem.observe(role="assistant", text="Congratulations on the move to Bangalore!")

# 3. Retrieve formatted context for prompt injection
messages = [{"role": "user", "content": "Where do I currently live?"}]
prompt_messages = mem.build_context(messages)
# prompt_messages contains a system prompt with current facts, outdated facts marked, and relevant quotes!

# 4. Search memory directly
results = mem.search("Where is my home?")
for state in results.states:
    print(state.text)  # "user · home city: Bangalore"

# 5. Background consolidation (extracts facts and closes outdated ones)
report = mem.sleep()
print(report)

mem.close()

---

Usage Option 2: Zero-Code Proxy (OpenAI SDK, LangChain, Cursor, Open WebUI)

Start Orma as a local proxy:

# With Ollama
orma proxy --model llama3.2:3b

# Or with llama.cpp
orma proxy --upstream http://127.0.0.1:9931 --model "Qwen/Qwen2.5-3B-Instruct-GGUF:Q4_K_M"

Then point any client to http://localhost:8080/v1:

With the Official OpenAI Python Client:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="none"
)

response = client.chat.completions.create(
    model="llama3.2:3b",
    messages=[{"role": "user", "content": "What is my job and where do I live?"}]
)
print(response.choices[0].message.content)

With LangChain:

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="http://localhost:8080/v1",
    api_key="none",
    model="llama3.2:3b"
)

With Open WebUI, AnythingLLM, or Cursor:

• Set OpenAI Base URL to: http://localhost:8080/v1
• Set API Key to: none

---

Usage Option 3: Interactive 3D Connectome Visualizer (orma viz)

Visualize your model's cognitive memory graph in real-time WebGL:

orma viz

This starts the memory visualizer and opens your browser directly to http://127.0.0.1:8080/_orma/viz:

• Anatomical Neocortical Connectome: Interactive 3D WebGL anatomical brain with translucent cortical lobes (Frontal, Parietal, Temporal, Occipital, Cerebellum, Brainstem) rendered with custom Fresnel rim shaders and gyral harmonics.
• Bilateral Hippocampal Seahorse Horns: Dedicated Cornu Ammonis seahorse structures and Fornix projection tracts linking the episodic memory hub directly to the prefrontal cortex.
• Real-time Sleep Replay Animation: Trigger consolidation to watch episodic orbs actively travel out of the hippocampal buffer and integrate into cortical memory nodes.
• Brain Region Mapping: Dedicated anatomical zones for Thalamic Hub (user identity), Prefrontal Cortex (canonical facts), Amygdala (forbidden constraints), Anterior Cingulate (conditional rules), and Temporal Cortex (semantic entities).
• Action Potential Pulses: Synaptic edges animate with directional photon particles based on recency and Hawkes burst frequency.
• Synapse Inspector: Click any node to see its exact sentence provenance citation ([s14]), historical timeline, and regional connectivity.
• Neural CV Hand Gestures (Webcam, 100% Client-Side): Press G or click GESTURES to toggle camera-driven controls: open palm to orbit, index finger to aim and hover, pinch or dwell to select, V-sign to zoom, and closed fist to pause—filtered through a One-Euro filter for jitter-free tracking.

---

Usage Option 4: One-Command Web UI (orma up)

If you are using llama.cpp or Ollama with a browser web UI, run:

orma up --upstream http://127.0.0.1:9931 --model "Qwen/Qwen2.5-3B-Instruct-GGUF:Q4_K_M"

This immediately:

1. Starts the Orma memory proxy on port 8080.
2. Automatically opens your default web browser to http://127.0.0.1:8080/#/.
3. Passes through the web UI frontend while transparently routing all chat completions through Orma's memory layer.

---

Usage Option 5: Model Context Protocol (MCP) Server for Coding Assistants

Orma natively speaks the Model Context Protocol (MCP) over standard stdio. This gives coding agents (Claude Code, Cursor, Antigravity IDE, Windsurf, Roo Code, Hermes) persistent, zero-latency memory across editing sessions without session amnesia.

flowchart LR
    subgraph Clients ["AI Coding Assistants & IDEs"]
        ClaudeCode["Claude Code"]
        Cursor["Cursor IDE"]
        Windsurf["Windsurf"]
        Antigravity["Antigravity / Roo / Hermes"]
    end

    subgraph Transport ["Standard stdio JSON-RPC 2.0"]
        RPC["JSON-RPC Channel (orma mcp)"]
    end

    subgraph MCPServer ["Orma MCP Server Layer"]
        RecallTool["orma_recall"]
        RememberTool["orma_remember"]
        ForbidTool["orma_forbid"]
        FactsTool["orma_facts"]
        ForgetTool["orma_forget"]
    end

    subgraph OrmaEngine ["Orma Local Cognitive Engine"]
        Hybrid["Hybrid BM25 + sqlite-vec Search"]
        InhibitoryEngine["Inhibitory Hoisting & Sutra Packing"]
        SleepDaemon["Background Sleep Consolidation Worker"]
        DB[("Embedded SQLite: ~/.orma/memory.db")]
    end

    Clients <-->|"stdio"| RPC
    RPC --> MCPServer
    MCPServer <--> OrmaEngine
    OrmaEngine <--> DB

In Claude Code:

claude mcp add orma -- orma mcp

In Cursor (.cursor/mcp.json or Settings > MCP):

{
  "mcpServers": {
    "orma": {
      "command": "orma",
      "args": ["mcp"]
    }
  }
}

In Windsurf / Antigravity IDE / Roo Code (mcp.json):

{
  "mcpServers": {
    "orma": {
      "command": "orma",
      "args": ["mcp"]
    }
  }
}

One-Click Install via Smithery.ai:

npx -y @smithery/cli install orma-ai --client cursor

Tools Exposed to Agents:

• orma_recall(query, space): Returns token-budgeted, Sutra-packed active facts, anti-patterns, and past decisions (< 20ms).
• orma_remember(text, kind, role, space): Permanently records a project decision, architecture rule, or user constraint. Set kind="anti_pattern" to mark a forbidden mistake to avoid.
• orma_forbid(rule, space): Directly registers a hard anti-pattern or prohibited behavior (e.g., "Never chain PowerShell commands with semicolons").
• orma_facts(space, include_history): Inspects all active canonical truths without running a search.
• orma_forget(state_id, space): Closes an obsolete or superseded constraint.

---

Inhibitory Control & Anti-Pattern Prevention (Negative Memory)

Anyone using coding assistants knows this pain: you tell the model "Stop using semicolons to chain commands in PowerShell", and two turns later it does it again. Autoregressive attention latches onto the forbidden token and repeats the exact error you asked it to avoid.

flowchart TD
    subgraph Problem ["Traditional LLM Attention Failure"]
        UserWarning["User: 'Never use semicolon to chain commands in PowerShell'"] --> StandardLLM["Standard LLM Attention Mechanism"]
        StandardLLM --> AttentionBias["Attention Activates on Forbidden Token: 'semicolon'"]
        AttentionBias --> RecurrenceError["Forbidden Mistake Repeated: git add . ; git commit"]
    end

    subgraph Solution ["Orma Inhibitory Control Architecture"]
        ForbidRule["Inhibitory Rule: orma_forbid / sleep extraction"] --> SchemaAttr["Schema Attribution (prohibited: true)"]
        SchemaAttr --> NamespaceAttr["Attribute Namespacing (forbidden_powershell_chain)"]
        NamespaceAttr --> HoistTop["Top-of-Prompt Hoisting: [FORBIDDEN: never use semicolon]"]
        HoistTop --> DynamicFraming["Dynamic Negative Framing Semantics"]
        DynamicFraming --> CleanOutput["Strict Negative Compliance: git add . \n git commit"]
    end

Orma introduces Inhibitory Control:

1. Schema-Level Attribution: Negative rules are identified during sleep extraction with prohibited: true or directly registered via orma_forbid(rule).
2. Sutra Inhibitory Hoisting: Prohibited states are rendered as [FORBIDDEN: <rule>] and hoisted to the very top of the system prompt (above all positive facts and conversation history).
3. Dynamic Negative Framing: Orma dynamically injects explicit negative constraint semantics into the system prompt whenever anti-patterns are present:

   ## Memory
   ... Lines marked [FORBIDDEN: ...] or under Forbidden are strict negative constraints: you must NEVER suggest, mention, or take what is forbidden.
   [FORBIDDEN: chaining terminal commands using semicolons or commas]
   [user.editor: neovim]
   

4. Universal Applicability: Works identically for developer pain points (terminal syntax, forbidden dependencies, deprecated API calls) and personal constraints (severe allergies, tone boundaries, forbidden buzzwords).