openloomi-memory

> **Note:** If OpenLoomi readiness is unknown, use `openloomi-setup` first. If OpenLoomi Desktop is not installed, follow [Getting Started](https://openloomi.ai/docs/getting-started).

# OpenLoomi Memory Skill

OpenLoomi Memory is the **long-lived context layer of OpenLoomi** — a tiered, locally-stored knowledge graph that grows on its own from your Connectors, chats, and Screen Capture. Memory is what makes Chat grounded and what Loop reads before it produces a Decision. It is always on your machine (local-first), always visible, and always auditable — see [Memory](https://openloomi.ai/docs/memory) for the full model.

This skill exposes three searchable surfaces over that context:

| Surface | What it is | Where it lives |
|---|---|---|
| **Memory files** | People, projects, notes, strategy — your hand-edited knowledge graph | `~/.openloomi/data/memory/` |
| **Knowledge Base** | Documents you uploaded (PDF, DOCX, TXT, MD, slides, sheets, images) chunked + embedded via RAG | openloomi server |
| **Insights** | AI-extracted records (decisions, action items, preferences, relationships, events) derived from chats and source messages, with usage analytics + automatic maintenance | openloomi server |

Use `search-all` whenever the user asks a general memory question — it covers all three surfaces in one call.

---

## Overview

**Tiered model.** OpenLoomi Memory spans four tiers that OpenLoomi reasons across simultaneously:

- **Raw information** — original messages, files, transcripts synced from your Connectors and Screen Capture.
- **Insights** — extracted entities, decisions, key events from chats and source messages. Each insight carries usage analytics (view frequency, sources, value score) and a maintenance cycle (daily analytics refresh, weekly compaction) that surfaces the most relevant records and prevents context decay.
- **Contextual memory** — recent conversation state, screen captures, and short-term references for the current task.
- **Knowledge-base memory** — the long-term people / projects / decisions / preferences graph that survives months of activity.

Together these let Chat ground answers in both immediate context and deep history at once. Loop reads the relevant slice before producing each Decision; the result of every approved Action is written back into Memory so the next judgement has sharper context.

**How it works with Connectors.** Memory is auto-built from the platforms you've authorized. Connectors handle the OAuth / app-credential / QR / interactive flows — see `openloomi-connectors` for the native 7 messaging apps and the Composio OAuth layer (1000+ apps including Slack, Discord, X, Gmail, Outlook, Google Calendar/Drive/Docs, GitHub, Notion, Linear, HubSpot, LinkedIn, Jira, Asana). Once connected, Memory continuously syncs raw messages, meetings, emails, tweets, calendar events, voice calls, and any notes or screen captures you've made.

---

## Authentication

The CLI auto-reads your token from `~/.openloomi/token` (base64 encoded JWT).

---

## Local Memory Filesystem

### Overview

Memory files are stored locally at `~/.openloomi/data/memory/` and searched via direct filesystem access. This is a **read-only** operation that performs case-insensitive text search across `.md` and `.json` files.

### Directory Structure

```
~/.openloomi/data/memory/
├── chats/           # Chat conversation exports
├── channels/         # Channel memory exports e.g., weixin, telegram, etc.
├── people/          # Person profiles
├── projects/       # Project notes
├── notes/          # General notes
└── strategy/       # Strategy documents
```

### Write Operations

Memory files are plain markdown or JSON stored locally. You can add or delete files directly.

**Adding a memory file:**
```bash
node $SKILL_DIR/scripts/openloomi-memory.cjs add-memory "Content to remember" --file=filename.md --directory=notes
```
- `--file` (optional): Filename. If not provided, auto-generated from first line of content.
- `--directory` (optional): Subdirectory under `~/.openloomi/data/memory/`. Created if doesn't exist.

**Deleting a memory file:**
```bash
node $SKILL_DIR/scripts/openloomi-memory.cjs delete-memory filename.md --directory=notes
```

### How search-memory Works

1. **Path**: `~/.openloomi/data/memory/` (or subdirectory if specified)
2. **Search Type**: Case-insensitive full-text search
3. **Files**: Scans `.md` and `.json` files recursively (max depth 5)
4. **Matching**: Each line is searched; returns first match per file
5. **Output**: File path, line number, and line preview (first 200 chars)

### Example Output

```json
{
  "results": [
    {
      "file": "people/boss.md",
      "line": 42,
      "preview": "My boss John mentioned the deadline is next Friday"
    },
    {
      "file": "projects/app/notes.md",
      "line": 10,
      "preview": "Boss wants the app launched by end of month"
    }
  ],
  "total": 2
}
```

---

## API Endpoints

### Knowledge Base (RAG)

#### POST `/api/rag/search` - Search Documents
Semantic search of uploaded documents using embeddings.

```bash
curl -X POST http://localhost:3414/api/rag/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "project plan", "limit": 5}'
```

**Parameters:**
- `query` (string, required) - Search query
- `limit` (number, default 5) - Max results to return

**Response:**
```json
{
  "results": [
    {
      "id": "doc_xxx",
      "title": "Project Document",
      "content": "...",
      "score": 0.95
    }
  ]
}
```

---

#### GET `/api/rag/documents` - List Documents
List all documents in the knowledge base.

```bash
curl http://localhost:3414/api/rag/documents?limit=50 \
  -H "Authorization: Bearer $TOKEN"
```

**Parameters:**
- `limit` (number, default 50) - Max results to return

**Response:**
```json
{
  "documents": [
    {
      "id": "doc_xxx",
      "name": "document.pdf",
      "type": "pdf",
      "size": 102400,
      "createdAt": "2024-01-01T00:00:00Z