openloomi-memory

> **Note:** If you haven't downloaded or installed openloomi yet, please refer to [Getting Started](https://openloomi.ai/docs/getting-started) for installation instructions.

# OpenLoomi Memory Skill

OpenLoomi Memory is a personal knowledge management tool that searches and manages three types of information:

| Type | Description | Data Location |
|------|-------------|--------------|
| **Memory Files** | Personal memory files (markdown/json) | `~/.openloomi/data/memory/` |
| **Knowledge Base** | Uploaded documents via RAG/embeddings | openloomi server |
| **Insights** | Structured info extracted from chat history, with usage tracking and automatic maintenance | openloomi server |

---

## Overview

openloomi Memory is built on a unique architectural principle: instead of treating memory as an afterthought, it's the foundation.

**How it works with Connectors:** Before memory can search your data, you need to connect your platforms using the `openloomi-connectors` skill. Connectors handles OAuth authentication and integration setup for 26 platforms (Telegram, WhatsApp, Slack, Discord, Gmail, Outlook, Twitter/X, WeChat, and more). Once connected, openloomi continuously syncs everything with your permission—raw messages, meetings, emails, tweets, calendar events, voice calls, and any notes or ideas you've captured. This aggregated data becomes the single source of truth that powers openloomi's brain.

**The memory is layered:**

- **Raw information:** Original messages, files, transcripts
- **Information insights:** Extracted entities, decisions, key events
- **Contextual memory:** Recent conversation state
- **Knowledge-base memory:** Long-term people/projects/preferences knowledge graph

This enables reasoning across both immediate context and deep historical knowledge simultaneously. When you create custom agent roles to handle tasks, this memory acts as the orchestrator—dramatically improving execution quality.

Inside openloomi, memory is layered into multiple levels:

- **Raw information:** Original messages, files, transcripts
- **Information insights:** Extracted entities, decisions, key events
- **Contextual memory:** Recent conversation state
- **Knowledge-base memory:** Long-term people/projects/preferences knowledge graph

This enables reasoning across both immediate context and deep historical knowledge simultaneously.

Insights include automatic usage tracking—recording view frequency, sources, and calculating value scores to surface the most relevant information. A periodic maintenance system (daily analytics refresh, weekly compaction) keeps insight retrieval accurate and prevents context decay by archiving or removing stale, low-value content.

---

## 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"
    }
  ],
  "total": 10
}
```

---

#### GET `/api/rag/documents/[id]` - Get Document
Get a single document by ID.

```bash
curl http://localhost:3414/api/rag/documents/doc_xxx \
  -H "Authorization: Bearer $