Version 0.1
Traditional AI memory is fleeting. Chatbots can remember the last few turns of a conversation but lack a deep, persistent understanding of their context. They don’t know the company’s products, understand its internal policies, or recognize the complex relationships between users, orders, and tickets. This results in repetitive, inefficient, and unintelligent user experiences.
Orma (from the Malayalam word ഓർമ്മ, meaning “memory” or “recollection”) is engineered to solve this fundamental problem. It is not merely a memory module; it is a pluggable, “live” knowledge core designed to serve as the comprehensive brain for any application, from customer support chatbots to complex internal agents.
Orma’s core principle is a clear separation of concerns:
Orma employs a hybrid, multi-layered data architecture where each component is optimized for a specific function: speed, persistence, or contextual reasoning.
| Component | Role | Analogy | Purpose & Data Stored |
|---|---|---|---|
| Redis | The Reflex System | The Spinal Cord | Handles high-speed, volatile data. Stores active session IDs, a “hot” buffer of recent messages for instant recall, and serves as a high-speed message broker (Pub/Sub) to trigger asynchronous background tasks. |
| Supabase (Postgres) | The Chronicle & Semantic Memory | The Journal | Provides immutable, persistent storage. It is the ground truth, storing the full transcript of every conversation. With the pgvector extension, it also stores vector embeddings for every message and ingested document, creating a searchable “semantic memory” of what was said or written. |
| Neo4j | The Cortex | The Brain’s Neural Network | Models deep context and relationships. Stores a structured knowledge graph of extracted entities (e.g., users, products, companies) and the relationships between them (e.g., PURCHASED, WORKS_FOR, MENTIONED_IN). This enables complex, multi-hop reasoning. |
Orma is not a static repository; it is a dynamic system designed to learn and improve over time. The Active Learning Framework operates continuously in the background to refine what Orma knows and how it retrieves that knowledge.
Not every piece of information in a conversation is a “fact” worth remembering. Orma uses a background LLM process to analyze conversational turns and assign a salience score.
Orma learns from the success and failure of its own context retrieval to improve future performance.
The knowledge graph is actively managed to ensure it remains accurate and efficient.
(User)-[:HAS_PRODUCT]->(Aura Pro) and (User)-[:OWNS]->(Aura Pro Headphones) can be consolidated into a single, canonical relationship.(Alex)-[:MANAGES]->(Bob)and (Bob)-[:MANAGES]->(Carol), it can create a new, inferred relationship (Alex)-[:HAS_INDIRECT_REPORT]->(Carol).For Orma to be a true knowledge core, it must be able to learn from the business’s entire data ecosystem. The Ingestion Framework makes this possible through two primary pipelines.
This pipeline syncs with external data sources that have a clear schema, like product catalogs or existing databases.
product_title -> ProductName).This pipeline ingests knowledge from sources like PDFs, documents, or websites.
The entire complexity of the Orma architecture is abstracted away behind a clean, simple Software Development Kit (SDK). A developer only needs to interact with two components.
OrmaMemory (For Conversational Context)A LangChain-compatible memory class that automatically manages the saving and loading of conversational turns. It handles the short-term hot buffer (Redis) and the long-term transcript (Supabase) seamlessly.
# Developer's Code
from my_memory_sdk import OrmaMemory
# Initialize with a session ID
memory = OrmaMemory(session_id="user_alex_123", api_key="pk_...")
# Plug it directly into a LangChain agent or chain
# Orma handles the rest automatically.
agent_executor = AgentExecutor(..., memory=memory)
OrmaKnowledgeClient (For Empowering Tools)A simple client for querying the entire unified knowledge base. This is the core of making the developer’s tools intelligent.
# Developer's Code
from my_memory_sdk import OrmaKnowledgeClient
knowledge_client = OrmaKnowledgeClient(api_key="pk_...")
# Query the knowledge core from within a custom tool
context = knowledge_client.query(
session_id="user_alex_123",
query_text="the headphones I bought last week",
query_mode="hybrid" # Use full Redis + Postgres + Neo4j power
)
# context is a rich JSON object with entities, summaries, and related docs.
The .query() method returns a structured JSON object, providing the developer’s tool with a synthesized understanding of the user’s request, ready for action.
// Sample response from knowledge_client.query()
{
"summary": "The user is asking about order #AX45-B7, which contains 'Aura Pro' headphones.",
"entities": [
{ "type": "OrderID", "value": "AX45-B7", "source": "Neo4j" },
{ "type": "Product", "value": "Aura Pro", "source": "Neo4j" }
],
"related_documents": [
{
"source": "return_policy.pdf",
"chunk": "Items can be returned within 30 days of purchase..."
}
]
}
get_order_status tool (written by the developer) is required.get_order_status tool is invoked.knowledge_client.query(query_text="my last order").session_id to find Alex’s most recent order in the Neo4j graph and returns the structured JSON: {"entities": [{"type": "OrderID", "value": "AX45-B7"}]}.OrderID and makes a secure call to the company’s private shipping API with that ID. Orma is not involved in this call.OrmaMemory object saves the entire interaction to the persistent logs in Supabase, and the Active Learning Framework analyzes the turn for salience and feedback.This workflow is fast, secure, and incredibly intelligent, leveraging the best of both worlds: Orma’s deep, self-improving knowledge and the developer’s specific business logic.
This blueprint represents the current state of the Orma project. For the latest updates and implementation details, please refer to the official documentation and repositories.