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:

ConceptWhat it isExampleAPI KeyYour identity ( X-API-Key header)a1b2c3d4-... (1 per user)Space IDA memory storage addresspersonal/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#

TermMeaningapiKey / OMEM_API_KEY / API key / secretAll refer to the same ourmem identifier. Prefer "API key" with users.tenantThe 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#

ToolPurposememory_storePersist facts, decisions, preferencesmemory_searchHybrid search (vector + keyword)memory_listList with filters and paginationmemory_getGet memory by IDmemory_updateModify content or tagsmemory_forgetRemove a memorymemory_ingestSmart-ingest conversation into atomic memoriesmemory_statsAnalytics and countsmemory_profileAuto-generated user profile

Lifecycle hooks (automatic):

HookTriggerPlatformSessionStartFirst messageAll — memories + profile injectedStopConversation endsClaude Code — auto-captures via smart ingestPreCompactBefore compactionClaude 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#

PlatformInstallConfigClaude Code/plugin marketplace add ourmem/omem``~/.claude/settings.json env fieldOpenCode"plugin": ["@ourmem/opencode"] in opencode.jsonplugin_config in opencode.jsonOpenClawopenclaw plugins install @ourmem/ourmem``openclaw.json with apiUrl + apiKeyMCPnpx -y @ourmem/mcp in MCP configOMEM_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:

TypeScopeExamplePersonalOne user, multiple agentsYour Coder + Writer share preferencesTeamMultiple usersBackend team shares architecture decisionsOrganizationCompany-wideTech 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.

MethodEndpointDescriptionPOST/v1/tenantsCreate workspace, get API keyPOST/v1/memoriesStore memory or smart-ingestGET/v1/memories/search?q=Hybrid searchGET/v1/memoriesList with filtersPOST/v1/importsBatch import filePOST/v1/spacesCreate shared spacePOST/v1/memories/:id/share-to-userOne-step cross-user sharePOST/v1/memories/share-all-to-userBulk cross-user shareGET/v1/statsAnalytics

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.