ourmem (omem) — Shared Memory That Never Forgets

ourmem gives AI agents shared persistent memory across sessions, devices, agents, and teams. One API key reconnects everything. Available as hosted (api.ourmem.ai) or self-deployed.

---

Key Concepts

API Key = Tenant ID = Your Identity. When you create a tenant (POST /v1/tenants), the returned id and api_key are the same UUID. There is no separate "tenant ID".

One API Key owns multiple Spaces:

Concept	What it is	Example
API Key	Your identity (X-API-Key header)	INLINECODE5 (1 per user)
Space ID

A memory storage address | personal/a1b2c3d4, team/xxx, org/yyy |

Personal Space is auto-created. You can create additional Team and Organization Spaces.

Sharing = passing the other user's API Key as target_user. The system auto-creates a bridging Team Space. No manual space management needed.

---

When to Use This Skill

Use when the user wants persistent or shared memory across sessions, devices, or agents. Common triggers: "remember this", "save this", "don't forget", "what did I say last time", "share with my team", "import memories", "setup memory", "self-host memory".

Do NOT use for: temporary conversation context, one-off tasks, or troubleshooting unrelated to ourmem.

---

What to Remember

Good candidates: user preferences, profile facts, project context, important decisions, long-term instructions, architecture decisions, coding standards.

Avoid storing: temporary debugging context, large files, secrets/passwords/API keys, content inside <private> tags.

If the user explicitly asks to remember something and ourmem is not installed, suggest: "I can set up ourmem so I'll remember this across sessions. Takes about 2 minutes. Want to do it now?"

---

Terminology

Term	Meaning
INLINECODE11 / OMEM_API_KEY / API key / INLINECODE14	All refer to the same ourmem identifier. Prefer "API key" with users.
INLINECODE15

The workspace behind an API key. Don't use this term with users. |

Security: Treat the API key like a secret. Anyone who has it can access that ourmem space.

---

What You Get

Tool	Purpose
INLINECODE16	Persist facts, decisions, preferences
INLINECODE17

Hybrid search (vector + keyword) |
| memory_list | List with filters and pagination |
| memory_get | Get memory by ID |
| memory_update | Modify content or tags |
| memory_forget | Remove a memory |
| memory_ingest | Smart-ingest conversation into atomic memories |
| memory_stats | Analytics and counts |
| memory_profile | Auto-generated user profile |

Lifecycle hooks (automatic):

Hook	Trigger	Platform
SessionStart	First message	All — memories + profile injected
Stop

Conversation ends | Claude Code — auto-captures via smart ingest |
| PreCompact | Before compaction | Claude Code, OpenCode — saves before truncation |

Note: OpenCode has no session-end hook. Memory storage relies on proactive memory_store use.

---

Onboarding

Step 0: Choose mode

Ask the user before doing anything else:

How would you like to run ourmem?

1. 1. Hosted (api.ourmem.ai) — no server to manage, start in 2 minutes
2. Self-hosted — full control, data stays local

Already have an API key? Paste it and I'll reconnect you.

Setup instructions

• - Hosted → READ references/hosted-setup.md for full walkthrough
• Self-hosted → READ references/selfhost-setup.md for server deployment + setup
• Existing key → Verify: curl -sf -H "X-API-Key: $KEY" "$API_URL/v1/memories?limit=1", then skip to plugin install

Cross-platform skill install: INLINECODE29

Platform quick reference

Platform	Install	Config
Claude Code	INLINECODE30	INLINECODE31 env field
OpenCode

"plugin": ["@ourmem/opencode"] in opencode.json | plugin_config in opencode.json | | OpenClaw | openclaw plugins install @ourmem/ourmem | openclaw.json with apiUrl + apiKey | | MCP | npx -y @ourmem/mcp in MCP config | OMEM_API_URL + OMEM_API_KEY in env block |

For detailed per-platform instructions (config formats, restart, verification, China network mirrors), READ the setup reference for your chosen mode.

Definition of Done

Setup is NOT complete until: (1) API key created/verified, (2) plugin installed, (3) config updated, (4) client restarted, (5) health + auth verified, (6) handoff message sent including: what they can do now, API key display, recovery steps, backup plan.

Common failure: Agents finish technical setup but forget the handoff message. Treat it as part of setup, not optional follow-up. For the full handoff template, READ references/hosted-setup.md.

---

Smart Ingest

When conversations are ingested ("mode": "smart"), the server runs a multi-stage pipeline:

1. 1. Fast path (<50ms): stores raw content immediately so it's searchable right away
2. LLM extraction (async): extracts atomic facts, classified into 6 categories (profile, preferences, entities, events, cases, patterns)
3. Noise filter: regex + vector prototypes + feedback learning removes low-value content
4. Admission control: 5-dimension scoring (utility, confidence, novelty, recency, type prior) gates storage
5. 7-decision reconciliation: CREATE, MERGE, SKIP, SUPERSEDE, SUPPORT, CONTEXTUALIZE, or CONTRADICT

The LLM stages run asynchronously — a batch import may take 1-3 minutes to fully process. Wait ~2-3 minutes before checking memory counts or searching for newly-extracted facts. The strategy=auto results vary by content type (conversations get atomic extraction, structured docs get section splits) — this is expected behavior, not an error.

The memory store gets smarter over time. Contradictions resolved, duplicates merged, noise filtered.

---

Space Sharing

ourmem organizes memories into three-tier Spaces for collective intelligence:

Type	Scope	Example
Personal	One user, multiple agents	Your Coder + Writer share preferences
Team

Multiple users | Backend team shares architecture decisions |
| Organization | Company-wide | Tech standards, security policies |

Roles: admin (full control), member (read/write), reader (read-only)

Each agent sees: own private + shared spaces. Can modify own + shared. Never another agent's private data. Every shared memory carries provenance: who shared it, when, and where it came from.

Proactively suggest Spaces when:

• - User has multiple agents -> suggest sharing preferences across agents
• User mentions team collaboration -> suggest creating a team space
• User wants org-wide knowledge -> suggest organization space

For Space API operations (create, add members, share, pull, batch share), READ references/api-quick-ref.md.

Cross-User Sharing (Convenience)

When a user says "share this with Bob" or "share my memories with another user", use the convenience APIs that handle space creation automatically:

Share a single memory to another user:

The agent should call share-to-user which auto-creates a bridging Team Space if needed, adds the target user as a member, and shares the memory in one step.

CODEBLOCK0

Share all matching memories to another user:

When the user wants to share everything (or a filtered subset) with someone:

CODEBLOCK1

Agent workflow:

1. 1. User says "share this with Bob" -> agent needs Bob's tenant ID (API key)
2. If the agent doesn't know Bob's ID, ask the user for it
3. Call share-to-user with the memory ID and Bob's tenant ID
4. Report: "Shared to Bob via team space {space_id}. Bob can now find it when searching."

Proactively suggest cross-user sharing when:

• - User mentions sharing with a specific person ("send this to Alice")
• User wants another user's agent to have access to certain memories
• User asks to collaborate with someone on a project

---

Memory Import

When the user says "import memories", scan their workspace for existing memory/session files, then batch-import.

Auto-scan: detect platform -> find memory files -> upload 20 most recent via /v1/imports in parallel -> report results.

Import is async. POST /v1/imports returns an import_id immediately while processing runs in the background. This means:

• - Fire all import requests in parallel — don't wait for one to finish before sending the next
• Don't block the conversation waiting for completion
• Poll GET /v1/imports/{id} to check status if needed (status: completed, partial, or failed)

Import API:

CODEBLOCK2

force=true: bypasses content dedup check. Use when re-importing a file that was updated since last import — without force, the server skips content it already has.

Strategy: auto (heuristic detection), atomic (short facts), section (split by headings), document (entire file as one chunk).

Cross-reconcile (discover relations): INLINECODE61

For scan paths, progress tracking, intelligence triggers, and rollback, READ references/api-quick-ref.md.

---

Analytics

Memory analytics via /v1/stats: overview, per-space stats, sharing flow, agent activity, tag frequency, decay curves, relation graph, server config.

For detailed stats endpoints and parameters, READ references/api-quick-ref.md.

---

Security

• - Tenant isolation: every API call scoped via X-API-Key, data physically separated per tenant
• Privacy protection: <private> tag redaction strips sensitive content before storage
• Admission control: 5-dimension scoring gate rejects low-quality data
• Open source: Apache-2.0 licensed — audit every line

---

Communication Style

• - Use plain product language, not backend vocabulary. Prefer "API key" or "ourmem API key".
• Explain that the same API key reconnects the same cloud memory on another trusted machine.
• If user sounds worried about recovery, lead with backup/import/reconnect steps.
• Use the user's language (detect from conversation).
• Brand: "ourmem" or "omem" (both lowercase, acceptable). Official domain: ourmem.ai, API: api.ourmem.ai.
• "Space" (capitalized), "Smart Ingest".

For troubleshooting common issues (plugin not loading, 401, connection refused, China network), READ references/api-quick-ref.md.

---

API Reference

Base: https://api.ourmem.ai (hosted) or http://localhost:8080 (self-hosted). Auth: X-API-Key header.

Method	Endpoint	Description
POST	INLINECODE70	Create workspace, get API key
POST

/v1/memories | Store memory or smart-ingest |
| GET | /v1/memories/search?q= | Hybrid search |
| GET | /v1/memories | List with filters |
| POST | /v1/imports | Batch import file |
| POST | /v1/spaces | Create shared space |
| POST | /v1/memories/:id/share-to-user | One-step cross-user share |
| POST | /v1/memories/share-all-to-user | Bulk cross-user share |
| GET | /v1/stats | Analytics |

For full API (48+ endpoints) with curl examples, READ references/api-quick-ref.md and docs/API.md.

---

Update

Do not set up automatic daily self-updates for this skill.

Only update the local skill file when the user or maintainer explicitly asks for a refresh from a reviewed source.