ourmem

ourmem (omem) — Shared Memory That Never Forgets

ourmem (also known as omem) gives AI agents shared persistent memory across sessions, devices, agents, and teams.

Most memory systems trap knowledge in silos. ourmem's three-tier Space architecture enables collective intelligence: knowledge flows across agents and teams with provenance tracking and quality-gated sharing. One API key reconnects everything. Available as hosted (api.ourmem.ai) or self-deployed.

---

Trigger phrases

Use this skill when the user expresses intent to store, recall, share, or manage long-term memory.

Common triggers include:

• "remember this"
• "save this for later"
• "don't forget that..."
• "what did I say last time?"
• "recall my preferences"
• "forget that"
• "share this with my team"
• "share this with Bob"
• "share my memories with another user"
• "import memories"
• "setup memory"
• "memory not working"
• "self-host memory"
• "deploy memory server"

---

When to use this skill

Use when the user wants persistent or shared memory across sessions, devices, or agents.

Typical situations:

• The user asks the agent to remember something for future sessions
• The user wants to recall or reconnect to existing long-term memory
• The user wants persistent memory instead of local/session-only memory
• The user wants to import existing memory files into ourmem
• The user is moving to a new machine and wants to keep the same memory
• The user wants multiple agents or workflows to share the same memory space
• The user mentions team collaboration or shared knowledge
• The user wants memory analytics or stats
• The user wants to self-host the memory server

When NOT to use this skill

Do not use for:

• Temporary conversation context that only matters right now
• One-off tasks that don't need long-term memory
• Troubleshooting unrelated to ourmem setup, import, or reconnection

---

What to remember / skip

Good candidates:

• User preferences
• Profile facts about the user
• Project context or ongoing work
• Important decisions made during conversations
• Long-term instructions or habits
• Architecture decisions, coding standards

Avoid storing:

• Temporary debugging context
• Large data or files (use file upload instead)
• Secrets, passwords, or API keys
• Content inside <private> tags

---

Memory intent detection

If the user explicitly asks to remember something ("remember this", "save this", "don't forget"), store the information using memory_store if ourmem is installed.

If ourmem is not installed yet, suggest installing it:

I can set up ourmem so I'll remember this across sessions. Takes about 2 minutes. Want to do it now?

---

Terminology

Use this distinction consistently:

Short rule: API key, apiKey, and secret may refer to the same ourmem identifier. Prefer saying "API key" to users. Use OMEM_API_KEY in config examples.

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

If the user asks "What is this for?" answer plainly:

This is the API key that reconnects you to your ourmem space. Your agent uses it to save and recall memory in the right place.

---

Definition of Done

This task is NOT complete until ALL of the following are true:

1. ourmem API key is created or verified reachable
2. Plugin is installed for the user's platform
3. Config is updated with correct URL and key
4. Client is restarted
5. Setup is verified (health + auth pass)
6. The user has been sent the full Step 5 handoff message, including:
   • What they can do now (import, remember, team space)
   • API key display
   • Recovery steps
   • Backup plan

---

Common failure mode

Agents often finish the technical setup and forget to send the required final handoff message. Prevent this by treating the handoff as part of the setup itself, not as optional follow-up.

---

What You Get

Lifecycle hooks (automatic, no agent action needed):

Note: OpenCode does not have a session-end hook. Memory storage in OpenCode relies on the agent proactively using the memory_store tool.

---

Onboarding

Step 0: Choose mode

[AGENT] 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 (Docker or binary on your machine) — full control, data stays local

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

Heads-up: your client will restart later in this setup. When that happens, please wait a moment, then send "Hi" to reconnect and continue.

Branching:

• Hosted -> READ references/hosted-setup.md for detailed setup, then continue from Step 1
• Self-hosted -> READ references/selfhost-setup.md for server deployment + setup, then continue from Step 1
• Existing key -> Verify it first (see below), then skip to Step 2

If the user provides an existing API key, verify reachability:

API_URL="${OMEM_API_URL:-https://api.ourmem.ai}"
API_KEY="<paste-from-user>"
curl -sf -H "X-API-Key: $API_KEY" "$API_URL/v1/memories?limit=1" \
  && echo "OK" || echo "UNREACHABLE"

• If OK: say "Great, your existing ourmem API key is reachable. I'll connect this setup to that same memory." Then continue to Step 2.
• If UNREACHABLE: say "I could not reach that API key. Please double-check it, or create a new one instead." Ask the user to retry or choose a fresh setup.

---

Step 1: Create API key

Skip this step if the user provided a working API key in Step 0.

[AGENT]

Hosted:

curl -sX POST https://api.ourmem.ai/v1/tenants \
  -H "Content-Type: application/json" \
  -d '{"name": "my-workspace"}' | jq .

Self-hosted:

curl -sX POST http://localhost:8080/v1/tenants \
  -H "Content-Type: application/json" \
  -d '{"name": "my-workspace"}' | jq .

Response:

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "api_key": "xxx-xxx-xxx",
  "status": "active"
}

Save the api_key value as API_KEY.

When explaining to the user, say:

Your new ourmem API key is ready. This key reconnects you to the same memory from any machine.

Important: this API key is also your secret. Never share it with anyone. If someone else gets it, they can access your memory.

---

Step 2: Detect platform and install

[AGENT] Auto-detect which platform is running. Do NOT ask the user to pick. Use this detection logic:

Detection order:

1. If claude CLI exists in PATH, or the environment looks like Claude Code -> Claude Code path
2. If opencode.json exists in the current directory or project root -> OpenCode path
3. If openclaw.json exists in the current directory or project root -> OpenClaw path
4. Otherwise -> MCP path (works with Cursor, VS Code, Claude Desktop, and others)

If detection is ambiguous, ask the user which platform they're using.

Quick reference per platform:

For detailed per-platform instructions (config file formats, jq commands, npm mirror detection for China networks), READ references/hosted-setup.md or references/selfhost-setup.md depending on the mode chosen in Step 0.

---

Step 3: Restart client

[AGENT] Tell the user a restart is needed and what to expect:

I'm restarting so the memory plugin loads. After the restart, send me a message to confirm everything is working.

This usually takes less than a minute.

Platform-specific restart:

• Claude Code: restart the claude process
• OpenCode: restart the opencode process
• OpenClaw: restart the gateway
• MCP clients: restart the app (Cursor, VS Code, Claude Desktop)

---

Step 4: Verify

[AGENT] After restart, run these checks:

API_URL="${OMEM_API_URL:-https://api.ourmem.ai}"

# 1. Health check (no auth needed)
curl -sf "$API_URL/health" && echo "Server OK"

# 2. Auth check
curl -sf -H "X-API-Key: $API_KEY" "$API_URL/v1/memories?limit=1" && echo "Auth OK"

A setup is successful if:

• The ourmem API is reachable (health returns OK)
• The API key authenticates successfully (auth returns OK or empty list)
• Empty results are acceptable for a newly created API key

If both pass, proceed to Step 5.

If health fails: "The ourmem server seems unreachable. Check your network connection and try again."

If auth fails: "Your API key didn't authenticate. Double-check the key value, or create a new one."

---

Step 5: Handoff

[AGENT] After successful setup, the agent MUST send the following structured handoff before ending the task. Do not summarize or remove any parts. Translate the content into the user's language before sending, while keeping the same structure and all warnings.

ourmem is ready.

WHAT YOU CAN DO NOW

1. Import your existing memories (recommended)
   Say: "import memories to ourmem"
   I'll scan local files and import your history automatically.

2. Just talk normally. I'll automatically remember important things.

3. Say "remember: [something]" to explicitly save a fact.

4. Say "create a team space" to share memories between agents.


YOUR OURMEM API KEY

  API Key: <your-api-key>
  Server:  <api-url>

This API key is your access key to ourmem.
Keep it private and store it somewhere safe.


RECOVERY

Reinstall the plugin with the same API key.
Your memory reconnects instantly.


BACKUP PLAN

Keep your original local memory/session files as backup.
Store the API key in a password manager or secure vault.
On a new machine: reinstall the plugin, configure the same API key, done.

Do not default to offering a synthetic write/read demo as the next step.

Preferred next-step order:

1. Guide the user to import historical memories
2. Explain the recovery path for a new machine or accidental loss
3. Explain local backup plus offsite backup
4. Only offer a live write/read verification if the user explicitly asks

---

Smart Ingest

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

1. LLM extraction: extracts atomic facts from conversation, classified into 6 categories (profile, preferences, entities, events, cases, patterns)
2. Noise filter: regex patterns + vector prototype matching + feedback learning removes low-value content
3. Admission control: 5-dimension scoring (utility, confidence, novelty, recency, type prior) gates what gets stored
4. 7-decision reconciliation: each fact is compared against existing memories: CREATE (new), MERGE (refine), SKIP (duplicate), SUPERSEDE (outdated), SUPPORT (reinforce), CONTEXTUALIZE (add nuance), or CONTRADICT (conflicting)

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

---

Space Sharing

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

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.

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:

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 to ourmem", scan their workspace for existing memory and session files, then batch-import them.

Auto-scan flow:

1. Detect agent_id from platform config (if available)
2. Scan workspace for memory/session files
3. Upload the 20 most recent files (by modification time) via /v1/imports
4. Upload in parallel for speed
5. Report results (imported/skipped/errors)

Paths to scan:

Import API:

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

Strategy parameter controls how content is chunked: auto (default, heuristic detection), atomic (short facts, minimal LLM), section (split by headings), document (entire file as one chunk).

Cross-reconcile (discover relations via vector similarity):

curl -sX POST "$API_URL/v1/imports/cross-reconcile" -H "X-API-Key: $API_KEY"

For full import API details (progress tracking, intelligence triggers, rollback), READ references/api-quick-ref.md.

---

Analytics

Memory analytics through the stats API:

• Overview (/v1/stats): totals by type, category, tier, space, agent + timeline
• Space overview (/v1/stats/spaces): per-space stats, member contributions
• Sharing flow (/v1/stats/sharing): who shared what, where, when
• Agent activity (/v1/stats/agents): per-agent memory creation, search counts
• Tag frequency (/v1/stats/tags): tag usage across spaces
• Decay curves (/v1/stats/decay?memory_id=X): Weibull decay visualization
• Relation graph (/v1/stats/relations): memory relationship network
• Server config (/v1/stats/config): decay parameters, retrieval settings

---

Security

• Tenant isolation: every API call is scoped to your tenant via X-API-Key. Data is physically separated per tenant.
• Privacy protection: <private> tag redaction strips sensitive content before storage.
• Admission control: 5-dimension scoring gate rejects low-quality or noisy data before it enters the memory store.
• Open source: Apache-2.0 licensed plugins. Audit every line of code.

---

Communication Style

When presenting onboarding or recovery instructions:

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

---

Troubleshooting

---

API Reference

Base: https://api.ourmem.ai (hosted) or http://localhost:8080 (self-hosted) Auth: X-API-Key: <api-key> header on all requests (except /health and POST /v1/tenants)

For full endpoint details with curl examples, READ references/api-quick-ref.md.

For the complete API documentation (35 endpoints), READ 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.