Back
Ahok Memory Docs
v2.0

Getting Started

Ahok Memory provides a drop-in, stateful, long-term memory layer for your AI agents. It goes beyond simple vector storage by incorporating temporal graphs, user entity tracking, and advanced retrieval dynamics (Recency, Frequency, Importance).

Install — Python

bash
pip install openmemory-py

Install — Node.js

bash
npm install openmemory-js

Quick Start (Python)

python
import asyncio
from openmemory.client import Memory

async def main():
    # 1. Initialize (uses local SQLite by default)
    mem = Memory()

    # 2. Add a memory
    await mem.add("I am a software engineer interested in AI.", user_id="user_123")

    # 3. Search related context
    context = await mem.search("What is my job?", user_id="user_123")
    print(context)
    # output: [{'content': 'I am a software engineer...', ...}]

asyncio.run(main())

Quick Start (Node.js)

javascript
import { Memory } from 'openmemory-js';

const mem = new Memory();
await mem.add("I prefer coffee over tea.", { user_id: 'user_123' });

const context = await mem.search("What do I drink?", { user_id: 'user_123' });
console.log(context);

Configuration

OpenMemory defaults to sqlite:///openmemory.db in the current directory. Configure via environment variables:

OPENMEMORY_DB_URLDatabase connection string (e.g. postgresql://...)
OPENMEMORY_DEBUGSet to true for verbose logging

Core Concepts

Ahok Memory differs from a standard vector DB by implementing a cognitive architecture inspired by human memory systems.

Memory Architecture

Episodic

Stores specific events and interactions.

Semantic

Stores generalized facts and knowledge derived from episodes.

Procedural

Stores how-to knowledge and learned skills.

Hierarchical Storage Graph (HSG)

Data is organized hierarchically — not dumped into a flat index:

  • SectorsHigh-level domains (e.g. Personal, Work, Code)
  • NodesIndividual memory units
  • EdgesRelationships between memories (temporal, semantic, or explicit)

Temporal Graph

Time is a first-class citizen. OpenMemory tracks creation time, last access (for decay), and the causal chain of events. This enables queries like "What did we talk about last week?" or "What happened before I mentioned the bug?"

Retrieval Scoring

When you call search(), memories are scored by three factors:

formula
Score = (Similarity × α) + (Recency × β) + (Importance × γ)

  Similarity  — semantic vector distance
  Recency     — time-decay function
  Importance  — coactivation frequency (how often recalled)

User Partitioning

All memories are strictly partitioned by user_id. In multi-user apps, User A never sees User B's memories.

Python SDK

bash
pip install openmemory-py

Memory — core class

python
from openmemory.client import Memory

mem = Memory()
add(content, user_id, metadata=None) → dict

Stores a new memory. Returns the created memory object (including ID).

search(query, user_id, limit=5) → list[dict]

Retrieves relevant memories by semantic similarity + recency. Returns list sorted by score.

delete(memory_id) → bool

Removes a memory by ID.

history(user_id) → list[dict]

Returns the temporal chain of interactions for a user.

OpenAI Wrapper

python
from openmemory.openai_handler import OpenAIWrapper
from openai import OpenAI

client = OpenAIWrapper(OpenAI(), memory_instance)

# Use exactly like the normal OpenAI client —
# long-term context is auto-injected into the system prompt
resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What are my preferences?"}]
)

LangChain Integration

python
from openmemory.integrations.langchain import OpenMemoryChatMessageHistory

history = OpenMemoryChatMessageHistory(user_id="u1")
history.add_user_message("Hi!")

Node SDK

bash
npm install openmemory-js

add(content, options)

Stores a memory.

typescript
import { Memory } from 'openmemory-js';

const mem = new Memory();

await mem.add("User likes spicy food", {
  user_id: "user_1",
  tags: ["food", "preference"],
});

search(query, options)

Retrieves relevant context.

typescript
const results = await mem.search("What food to order?", {
  user_id: "user_1",
  limit: 5,          // optional, default 5
});

console.log(results[0].content);
// "User likes spicy food"

Server Mode

The Node package also ships a full HTTP API server:

bash
# Start on port 8080 (default)
npx openmemory-js serve

# Custom port
npx opm serve --port 9000

API Server

OpenMemory exposes a REST API for language-agnostic integration. Default base URL: http://localhost:8080

POST /memory/add

json
// request body
{
  "content": "My cat's name is Luna",
  "user_id": "user_123",
  "tags": ["pet"]
}

POST /memory/search

json
// request body
{
  "query": "What is the pet name?",
  "user_id": "user_123",
  "limit": 3
}

// response
{
  "memories": [
    {
      "id": "mem_abc123",
      "content": "My cat's name is Luna",
      "score": 0.89
    }
  ]
}

GET /health

Returns 200 OK if the system is running.

Run with Docker

bash
docker run -p 8080:8080 openmemory/server

Run from source

bash
git clone https://github.com/thierryteisseire/long-memory
cd long-memory
cp .env.example .env

cd backend
npm install
npm run dev   # listens on :8080

MCP & IDE Integration

Ahok Memory ships a native MCP server. Any MCP-aware client can treat it as a tool — no manual wiring needed.

Claude / Claude Code

bash
claude mcp add --transport http openmemory http://localhost:8080/mcp

Cursor / Windsurf

Add to your .mcp.json:

json
{
  "mcpServers": {
    "openmemory": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Available MCP Tools

openmemory_storeSave a new memory
openmemory_querySemantic search across memories
openmemory_listList all memories for a user
openmemory_getFetch a single memory by ID
openmemory_reinforceBoost a memory's importance score

FAQ

How does this differ from Chroma or Pinecone?

Ahok Memory is an agentic memory layer, not just a vector database. It handles user separation, temporal tracking, and memory dynamics (decay, reinforcement) out of the box — without you wiring any of it.

Can I use it with any LLM?

Yes. It is model-agnostic. Works with OpenAI, Anthropic Claude, or local models (e.g. Llama 3 via Ollama).

Is my data persistent?

Yes. By default it uses SQLite (saved to a local file). You can configure Postgres for production scaling via the OPENMEMORY_DB_URL environment variable.

Can I self-host it?

Absolutely — that is the default mode. Run it locally with SQLite or deploy the Docker image to your own infra. No data ever leaves your environment.

What is the v2.0 Hyper-Structured Graphs feature?

v2.0 introduces a richer waypoint graph engine with associative, traversable links between memories — enabling multi-hop reasoning and explainable recall traces.

Ready to get started?

Launch the dashboard and connect your first agent.

Launch Dashboard