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)
• 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  # 213 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:

• Neocortical Connectome: Interactive 3D WebGL neural network showing active states (green), hard anti-patterns (crimson), defeasible rules (amber), and entity hubs (cyan).
• Action Potential Pulses: Synaptic edges animate with directional photon particles based on recency and Hawkes burst frequency.
• Spreading Activation: Search any topic to fly the 3D camera to that node and watch activation ripple across connected neighbors.
• Synapse Inspector: Click any node to see its exact sentence provenance citation ([s14]) and historical timeline.
• Hippocampal Buffer: Live drawer displaying the recent episodic turn stream and pending sleep consolidations.

---

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).

---

Multi-User & Multi-Tenant Isolation

Orma supports isolated memory spaces out of the box so multiple users or agent sessions don't contaminate each other's memories:

• In Python SDK:

  mem.add("Alice likes green tea.", space="user_alice")
  context = mem.build_context(messages, space="user_alice")
  

• In HTTP Requests / Proxies: Pass the x-orma-space header or "user" field:

  curl http://localhost:8080/v1/chat/completions \
    -H "x-orma-space: user_123" \
    -H "Content-Type: application/json" \
    -d '{"messages": [{"role": "user", "content": "Who am I?"}]}'
  

---

CLI Reference

Orma provides a command-line tool for managing your memory:

# Add a note or document
orma add "My dentist is Dr. Rao in Kothrud."
orma add docs/handbook.md

# Search memory
orma search "dentist"

# Inspect active facts and outdated history
orma facts --history

# Preview the exact prompt block that would be injected
orma recall "Who is my dentist?"

# Manually trigger sleep consolidation
orma sleep --model llama3.2:3b

# Forget a specific fact
orma forget 12

# Database statistics
orma stats

# Launch interactive 3D Cognitive Connectome WebGL visualizer
orma viz

# Run as an MCP server for Claude Code / Cursor / Windsurf
orma mcp

---

Memory Prompt Output Format (Sutra Dense Packing)

When Orma recalls memories, it packs them into an unambiguous, high-density symbolic bracket representation (saving 35–45% context tokens over conversational prose):

## Memory
What you remember about the person you are talking to, from earlier conversations, notes and documents. Answer directly using these facts and statements without asking the user to re-confirm details already provided here; do not mention this list. A line marked [outdated] was true when it was said and has changed since. Today is 2026-11-01.

[user.home city: Bangalore (since 2026-10-17)]
[user.morning drink: black coffee]
[user.morning drink | cond: sore throat -> warm ginger tea with raw honey]
[user.role: systems engineer @ Zerodha]
[EVENT: 2026-11-01: user received a gift from manager: Swiss knife]
[LOG: 2026-10-10 user: I'm Sahil and I live in Pune. [outdated: now Bangalore]]

(Note: Can be toggled back to classic natural language section blocks via enable_sutra_packing = False)

---

Cognitive & Mathematical Architecture

Orma integrates established principles from cognitive science, stochastic point processes, and non-monotonic logic directly into its zero-latency retrieval engine:

+---------------------------------------------------------------------------------------------------+
|                                 ORMA COGNITIVE RETRIEVAL PIPELINE                                 |
+------------------------------------+--------------------------------------------------------------+
| Hybrid Search (BM25 + sqlite-vec)  | Multi-channel fusion calibrated against dynamic noise floor  |
| Spreading Activation (ACT-R)       | Associative entity graph traversal with Fan Effect damping   |
| Hawkes Temporal Burst Process      | Self-exciting exponential kernel for conversational momentum |
| Ebbinghaus Retention & Stability   | Dynamic stability scaling per spaced repetition & rehearsal  |
| Defeasible Epistemic Logic         | Conditional exception handling preventing false overwrites   |
| Sutra Context Packing              | Dense declarative bracket encoding saving 35-45% tokens      |
+------------------------------------+--------------------------------------------------------------+

---

1. Hawkes Self-Exciting Temporal Process (enable_hawkes)

Cognitive Rationale: Human dialogues exhibit natural clustering and temporal burstiness (Hawkes 1971, Kleinberg 2002). When a user brings up a topic (e.g., an ongoing project or medical symptom), subsequent exchanges revolve around that cluster. Standard recency decay either forgets past topics too fast or keeps them active too long.

Mathematical Formulation:

Intensity(t) = alpha * exp(-beta * dt)
beta = ln(2) / half_life_seconds

• Burst Amplitude (alpha = 0.4): Boosts items accessed in active conversational bursts.
• Decay Constant (beta = ln(2) / 1800): A 30-minute half-life ensures topics discussed earlier in a session maintain strong conversational momentum without lingering indefinitely into future days.
• Bounded Ranking: Implemented in orma/recall/rank.py as a bounded additive boost so temporal bursts never override exact factual matches.

---

2. Ebbinghaus Spaced Repetition Stability (enable_ebbinghaus)

Cognitive Rationale: The human forgetting curve (Ebbinghaus 1885, Cepeda et al. 2008) demonstrates that memory retention decays exponentially, but each spaced retrieval increases the memory's underlying stability (half-life). A fact stated once in passing should gracefully fade, whereas a fact confirmed across 4 different days should remain permanently accessible.

Mathematical Formulation:

Retention R(dt) = exp(-dt / S)
Stability S(n)  = S0 * (1 + gain * (n - 1))

• Baseline Stability (S0 = 2.0 days): Initial stability for a single mention.
• Rehearsal Gain (gain = 0.5): For every subsequent citation or spaced rehearsal n, memory stability expands linearly, lengthening the half-life before decay.
• Dual Protection: Single-pass noise drops out of recall candidate pools, while repeated preferences resist decay for months.

---

3. ACT-R Spreading Activation & Anderson's Fan Effect (enable_spreading_activation)

Cognitive Rationale: Human memory recalls information associatively (Anderson 1983). When asked "Where should I go for my toothache?", the query may not contain the doctor's name, but the concept of toothache is associatively linked to dentist and Dr. Rao. Traditional graph databases (e.g. Neo4j) add 50–150ms of network overhead. Orma executes associative graph traversal directly within SQLite using indexed adjacency tables.

Mathematical Formulation:

Activation A_i = B_i + sum_j (W_j * S_ji)
Association S_ji = Base_Weight / Fan(Entity_j)

• Source Seed Extraction: Seed entities are identified from hybrid text matches and active states.
• The Fan Effect: John R. Anderson's Fan Effect proves that associative activation spreading from a concept is inversely proportional to the number of facts associated with it:
  • A specific entity (e.g., "Dr. Rao" with Fan = 2) channels 50% of its associative energy directly to the target clinic state.
  • A general hub (e.g., "Pune" with Fan = 60) dissipates its energy across dozens of states, preventing generic concepts from hijacking the recall budget.

---

4. Defeasible Epistemic Logic (enable_defeasible_logic)

Cognitive Rationale: Real-world beliefs are non-monotonic. When a user states:

"I drink black coffee every morning." followed later by: "When I have a sore throat, I drink ginger tea with honey."

Naive memory systems (like Mem0 or basic graph extraction) detect a contradiction on the entity-attribute (user, drink) and destructively overwrite the baseline habit.

Epistemic Rule Engine:

• Orma inspects assertions via schema attribution (item.condition extracted by the model during sleep) rather than brittle keyword matching.
• Categorical Assertions (condition: "" e.g., "I moved to Bangalore"): Trigger state supersession (active = 0, superseded_by_id = new_state_id).
• Defeasible Overrides (condition: "sore throat" e.g., "When sick, drink tea"): Registered as conditional exceptions without closing or corrupting the baseline categorical truth. Both facts are preserved in context.

---

5. Adaptive Noise Floor Calibration & Reciprocal Rank Fusion

Algorithmic Rationale: Small embedding models (e.g., 384-dimensional bge-small-en-v1.5) suffer from geometric concentration on high-dimensional unit hyperspheres—unrelated sentences frequently score 0.45–0.55 cosine similarity by pure random chance.

• Noise Floor Estimation: Orma dynamically samples pairwise distances to compute the 50th-percentile noise floor of the embedding space.
• Similarity Floor Truncation: Scores below the space noise floor carry zero evidential weight.
• Reciprocal Rank Fusion (RRF):

  RRF Score = (1 / (60 + Rank_BM25)) + (1 / (60 + Rank_Vector))
  

  Fuses exact keyword recall (FTS5 BM25) with semantic vector search (sqlite-vec) with zero hyperparameter tuning.

---

6. Sutra Context Encoding (enable_sutra_packing)

Cognitive & LLM Rationale: Small 3B models are heavily trained on code and structured JSON. Natural language narrative memory blocks ("Now true:", "Things said before:") waste precious context budget on formatting boilerplate and can cause models to ask redundant clarifying questions.

• Dense Declarative Syntax: Packs states, conditions, events, and outdated lineages into atomic bracketed forms ([user.attribute: value (metadata)]).
• Token Savings: Reduces prompt memory overhead by 35% to 45%, providing faster generation speeds and more room for user instructions.
• Zero Syntax Bleed: Formatted to ensure instruction-tuned models absorb the knowledge as background system facts without outputting brackets to the user.

---

7. Inhibitory Control & Attention Hoisting

Cognitive & Neuro-Symbolic Rationale: In human cognitive neuroscience, executive inhibitory control (prefrontal cortex) suppresses prepotent motor or verbal impulses. In autoregressive Transformers, negative phrasing ("do not use X") paradoxically increases the probability of generating X because token attention activates on the semantic representations of the mentioned words.

• Hoisting Precedence: Rather than interweaving negative rules inside narrative facts, Orma isolates negative boundaries into [FORBIDDEN: <rule>] tokens and places them at the very beginning of the system prompt.
• Instruction-Tuning Alignment: Modern instruction-tuned models (e.g. Qwen 2.5, Llama 3.2, Claude 3.5) treat top-level boundaries as hard system constraints when defined prior to task context.
• Dual Channel Registration:
  • Declarative Extraction: Asynchronous sleep maps "never use semicolon in terminal" to prohibited = True and namespaced attribute forbidden_<name>.
  • Immediate MCP Tool: Coding assistants directly call orma_forbid(rule) to establish an instant guardrail without waiting for background consolidation.

---

Storage & Data Durability (100% Local & Persistent)

• Single File SQLite Storage: All memories reside in ~/.orma/memory.db with Write-Ahead Logging (WAL) enabled.
• Survives Restarts & Power Cycles: You can shut down orma up, restart your machine, or close your terminal at any time; your complete memory state, episodic history, and consolidated facts remain permanently stored.
• Lossless Append-Only: Episodes are never destructively overwritten or pruned by hallucinating models. You can inspect or re-consolidate your history anytime with orma facts --history.

---

Configuration & Ablation Switches

Every mechanism in Orma can be independently configured or ablated in orma/config.py or passed via OrmaConfig:

Parameter	Default	Description
enable_semantic	True	Background consolidation into states & events (off = pure episodic sentence search baseline)
enable_novelty_gate	True	Drops duplicate sentences (cosine similarity >= 0.97)
enable_similarity_weighting	True	Calibrates vector similarity against adaptive space noise floor
enable_base_level	True	ACT-R recency and frequency power-law decay
enable_hawkes	True	Hawkes self-exciting temporal process for conversational bursts
enable_ebbinghaus	True	Ebbinghaus spaced repetition stability scaling
enable_spreading_activation	True	Associative spreading activation with Fan Effect
enable_defeasible_logic	True	Non-monotonic conditional exception protection
enable_sutra_packing	False	Dense declarative bracket encoding (-40% token usage; default False, toggle to True)
budget_tokens	4096	Token budget ceiling for injected memory blocks
search_k	30	Top-k candidates pulled per hybrid search channel
rrf_k	60	Reciprocal Rank Fusion constant for combining BM25 and vector scores

---

License

Distributed under the Apache-2.0 License. See LICENSE for more information.