Core concepts
A quick mental model before you touch any code.
Memory
A memory is a small piece of text OraMemory stores for one of your AI agents — a preference, a fact, a past decision, a user profile note. Every memory has:
| Field | Meaning |
|---|---|
content |
The text itself. |
agent_id |
Which agent owns it (e.g. "support", "coder"). |
user_id |
Optional — scope a memory to an end-user of your app. |
session_id |
Optional — scope to one conversation. Auto-generated if absent. |
tags[] |
Free-form labels for filtering. |
category |
A single broader bucket (e.g. "preferences", "schedule"). |
importance |
0–1, used when ranking search results. |
layer |
l1–l5, from volatile context buffer to long-term identity. |
embedding |
1536-dim vector stored automatically — you don't set it. |
When you read (search), OraMemory compares your query's embedding to stored embeddings using cosine similarity and returns ranked results.
Agent
An agent is any AI system you want to give memory. Agents are identified by a string — you pick the name. An agent can be:
- A product like Claude Code, Cursor, or your own chatbot.
- One AI persona inside a bigger app (
"support-bot","coach"). - A specific user's assistant (
"user-42-assistant").
Memories are scoped to an agent_id by default; cross-agent reads are opt-in.
Project
A project is a tenant — every memory, API key, and webhook belongs to exactly one project. Create as many projects as you need in the dashboard. A good rule of thumb: one project per deployed product.
API key
Each project issues API keys (om_live_… or om_test_…). We only store a SHA-256 hash — the plaintext is shown exactly once at creation. Revoke keys anytime from the dashboard.
Local vs managed vs self-hosted
| Mode | Where memories live | Who can read them |
|---|---|---|
| Local | SQLite file on your machine | Only you |
| Managed | Our Postgres (oramemory.com/api/v1) |
Anyone with your API key |
| Self-hosted | Your own Postgres + API deployment | You choose |
The same SDK and API works across all three.
Audit trail & versioning
Every add, update, and delete is logged. Every content change snapshots a new version row — see memory.history(). Your data is never silently rewritten.