Ourmem

Shared memory that never forgets. Cloud hosted or self-deployed. Collective intelligence for AI agents with Space-based sharing across agents and teams. Use when users say: "install ourmem" / "install omem" "setup memory" / "setup omem" "add memory plugin" "ourmem onboarding" / "omem onboarding" "memory not working" "remember this" "save this for later" "don't forget" "recall preferences" "what did I say last time" "import memories" "share memories" "share with user" "share memories to someone" "team memory" "shared space" "persistent memory" "cross-session memory" "collective intelligence" "memory analytics" "memory stats" "self-host memory" "deploy memory server" Even if the user doesn't say "ourmem" or "omem", trigger when they want persistent memory, memory sharing between agents, memory analytics, or memory import/export.

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)	a1b2c3d4-... (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
apiKey / OMEM_API_KEY / API key / secret	All refer to the same ourmem identifier. Prefer "API key" with users.
tenant	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
memory_store	Persist facts, decisions, preferences
memory_search	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. 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: npx skills add ourmem/omem --skill ourmem -g

Platform quick reference

Platform	Install	Config
Claude Code	/plugin marketplace add ourmem/omem	~/.claude/settings.json 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. 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.

bash

curl -sX POST "$API_URL/v1/memories/MEMORY_ID/share-to-user" \
  -H "Content-Type: application/json" -H "X-API-Key: $KEY" \
  -d '{"target_user": "TARGET_USER_TENANT_ID"}'
# Returns: { "space_id": "team/xxx", "shared_copy_id": "yyy", "space_created": true }

Share all matching memories to another user:

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

bash

curl -sX POST "$API_URL/v1/memories/share-all-to-user" \
  -H "Content-Type: application/json" -H "X-API-Key: $KEY" \
  -d '{"target_user": "TARGET_USER_TENANT_ID", "filters": {"min_importance": 0.7}}'
# Returns: { "space_id": "team/xxx", "space_created": false, "total": 80, "shared": 15, ... }

Agent workflow:

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:

bash

# Basic import
curl -sX POST "$API_URL/v1/imports" -H "X-API-Key: $API_KEY" \
  -F "file=@memory.json" -F "file_type=memory" -F "strategy=auto"

# Re-import an updated file (bypass content dedup)
curl -sX POST "$API_URL/v1/imports" -H "X-API-Key: $API_KEY" \
  -F "file=@memory.json" -F "file_type=memory" -F "strategy=auto" -F "force=true"

# Check import status
curl -s "$API_URL/v1/imports/IMPORT_ID" -H "X-API-Key: $API_KEY"

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): curl -sX POST "$API_URL/v1/imports/cross-reconcile" -H "X-API-Key: $API_KEY"

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	/v1/tenants	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.