ourmem

What this skill does

# 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:

| Internal term | User-facing explanation |
|---------------|------------------------|
| `apiKey` / `OMEM_API_KEY` | The ourmem API key. Sends as `X-API-Key` header. |
| `API key` | Preferred user-facing term. Say "ourmem API key" or just "API key". |
| `secret` | Treat as the same value as the API key unless the user clearly means something else. |
| `tenant` | The workspace behind an API key. Don't use this term with users. |

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

| Tool | When |
|------|------|
| `memory_store` | Persist facts, decisions, preferences, context |
| `memory_search` | Find memories by keywords and meaning (hybrid search) |
| `memory_list` | List memories with filters and pagination |
| `memory_get` | Retrieve a specific memory by ID |
| `memory_update` | Modify existing memory content or tags |
| `memory_forget` | Remove a memory |
| `memory_ingest` | Smart-ingest conversation into atomic memories |
| `memory_stats` | View memory analytics and counts |
| `memory_profile` | Get auto-generated user profile |

Lifecycle hooks (automatic, no agent action needed):

| Hook | Trigger | What happens | Platform |
|------|---------|--------------|----------|
| SessionStart | First message in new session | Memories + user profile injected into context (once per session, semantic search) | All |
| Stop | Conversation ends | Last messages auto-captured via smart ingest | Claude Code |
| PreCompact | Before context compaction | Saves memories before context is truncated | Claude Code, OpenCode |

> **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:

```bash
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:**

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

**Self-hosted:**

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

Response:

```json
{
  "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