Openloomi Memory

---
name: openloomi-memory
description: "openloomi Memory tools - search and manage the holistic context (people, projects, decisions, knowledge base, chat insights). Triggers: memory search, knowledge base, search documents, list insights, who is John, what did we decide about X, tiered memory, knowledge graph, people/projects/decisions, search-all, conversation memory"
allowed-tools: Bash(node $SKILL_DIR/scripts/openloomi-memory.cjs *)
---

> **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 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"
    }
  ],
  "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 $TOKEN"
```

**Response:**
```json
{
  "id": "doc_xxx",
  "name": "Project Document.pdf",
  "type": "pdf",
  "size": 102400,
  "content": "Document text content...",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}
```

---

### Insights

Insights are structured information extracted from chat history, such as key decisions, action items, and relationship notes. Each insight belongs to one or more **groups** (channels/platforms) like `gmail`, `telegram`, `whatsapp`, `slack`, `discord`, `linkedin`, `twitter`, etc.

#### GET `/api/insights` - List Insights
List all insights from a time period.

```bash
curl "http://localhost:3414/api/insights?days=7&limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

**Parameters:**
- `days` (number, default 7) - Look back period in days
- `limit` (number, default 50) - Max results to return

**Insight Structure:**
Each insight contains a `groups` field—an array of channel identifiers indicating which platform(s) the insight came from:

```json
{
  "id": "insight_xxx",
  "chatId": "chat_xxx",
  "type": "decision",
  "content": "John sent an email about the project deadline",
  "groups": ["gmail"],
  "people": ["John"],
  "time": "2024-01-01T00:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z"
}
```

**Insight Types:**
| Type | Description |
|------|-------------|
| `decision` | Key decisions made |
| `action_item` | Tasks or follow-ups |
| `note` | General notes |
| `preference` | User preferences |
| `relationship` | Notes about people |
| `event` | Important events |

**Common Channel Groups:**
| Channel | Group Value | Description |
|---------|-------------|-------------|
| Gmail | `"gmail"` | Google Mail messages |
| Outlook | `"outlook"` | Microsoft Outlook emails |
| Telegram | `"telegram"` | Telegram chats |
| WhatsApp | `"whatsapp"` | WhatsApp messages |
| Slack | `"slack"` | Slack messages |
| Discord | `"discord"` | Discord messages |
| LinkedIn | `"linkedin"` | LinkedIn messages |
| Twitter/X | `"twitter"` | Twitter posts |
| WeChat | `"weixin"` | WeChat messages |
| RSS | `"rss"` | RSS feed items |

---

#### POST `/api/insights` - Create Insight
Create a new insight manually.

```bash
curl -X POST http://localhost:3414/api/insights \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "preference", "content": "I prefer Americano coffee", "groups": ["whatsapp"]}'
```

**Parameters:**
- `type` (string, required) - Insight type (decision, action_item, note, preference, relationship, event)
- `content` (string, required) - The insight text
- `groups` (array, optional) - Channel groups to associate with
- `people` (array, optional) - People mentioned in the insight

**Response:**
```json
{
  "id": "insight_xxx",
  "type": "preference",
  "content": "I prefer Americano coffee",
  "groups": ["whatsapp"],
  "createdAt": "2024-01-01T00:00:00Z"
}
```

---

#### PUT `/api/insights/[id]` - Update Insight
Partial update an existing insight. Arrays (details, timeline, insights) are appended to, not replaced.

```bash
curl -X PUT http://localhost:3414/api/insights/insight_xxx \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": {
      "description": "Updated description",
      "details": [{"content": "User mentioned new preference", "person": "User"}],
      "timeline": [{"summary": "Progress update", "label": "Update"}]
    }
  }'
```

**Update Fields:**
- `title` - New title
- `description` - New description
- `importance` - Important, General, Not Important
- `urgency` - As soon as possible, Within 24 hours, Not urgent, General
- `details` - Array of detail objects (appended to existing)
- `timeline` - Array of timeline events (appended to existing)
- `myTasks` - Array of task objects
- `groups` - Array of group tags (replaced)
- `categories` - Array of categories (replaced)
- `people` - Array of people names (replaced)

**Response:**
```json
{
  "message": "Insight updated successfully",
  "id": "insight_xxx"
}
```

---

#### GET `/api/insights/[id]?fetch=true` - Get Insight
Get a single insight by ID, including associated chat.

```bash
curl "http://localhost:3414/api/insights/insight_xxx?fetch=true" \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**
```json
{
  "id": "insight_xxx",
  "chatId": "chat_xxx",
  "type": "decision",
  "content": "User decided to start new project next month",
  "chat": {
    "id": "chat_xxx",
    "title": "Chat with John",
    "messages": [...]
  },
  "createdAt": "2024-01-01T00:00:00Z"
}
```

---

#### DELETE `/api/insights/[id]` - Delete Insight
Delete a specific insight.

```bash
curl -X DELETE http://localhost:3414/api/insights/insight_xxx \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**
```json
{
  "success": true
}
```

---

#### GET `/api/chat-insights?chatId=xxx` - Get Chat Insights
Get all insights for a specific chat.

```bash
curl "http://localhost:3414/api/chat-insights?chatId=chat_xxx" \
  -H "Authorization: Bearer $TOKEN"
```

---

### Insight Usage Analytics & Maintenance

openloomi tracks insight usage and performs periodic maintenance to preserve retrieval quality, avoiding context decay.

#### Usage Tracking

Each insight view is recorded with:
- Access timestamp
- Access source (`list`, `detail`, `search`, `favorite`)
- Cumulative access counts (7-day / 30-day / total)

Data is stored in the `insightWeights` table:
- `accessCountTotal` - Total access count
- `accessCount7d` - Access count in last 7 days
- `accessCount30d` - Access count in last 30 days
- `lastAccessedAt` - Last access timestamp

#### Analysis Dimensions

Each insight is scored on trend and value:

| Metric | Weight | Description |
|--------|--------|-------------|
| Frequency | 45% | Based on 7-day / 30-day access frequency |
| Freshness | 25% | Last access time |
| Relevance | 20% | Importance (70%) + Urgency (30%) |
| Favorites | 10% | Whether the insight is favorited |

**Trend Indicators:**
- `rising` - Access frequency increasing
- `falling` - Access frequency decreasing
- `stable` - Frequency stable

#### Periodic Maintenance

System automatically runs two maintenance tasks:

| Task | Frequency | Purpose |
|------|-----------|---------|
| Daily analytics refresh | 24 hours | Refresh access stats, recalculate trends and scores |
| Weekly compaction | 7 days | Merge similar insights, prune low-value content |

**Retention Policy:**
- `delete`: 90 days no access + low score + not high importance → soft delete, hard delete after 180 days
- `archive`: 30 days no access + low score OR falling trend + low score → archived

#### GET `/api/insights/analytics` - Get Insight Usage Analytics

```bash
curl "http://localhost:3414/api/insights/analytics" \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**
```json
{
  "generatedAt": "2024-01-15T10:30:00Z",
  "summary": {
    "totalInsights": 150,
    "activeInsights": 45,
    "dormantInsights": 105,
    "totalAccesses30d": 230,
    "averageValueScore": 42,
    "risingInsights": 12,
    "fallingInsights": 8,
    "stableInsights": 25
  },
  "topInsights": [...],
  "bottomInsights": [...],
  "relationships": [...],
  "insights": [
    {
      "id": "insight_xxx",
      "title": "User decided to start new project",
      "description": "",
      "taskLabel": "",
      "platform": "gmail",
      "account": "user@gmail.com",
      "importance": "general",
      "urgency": "not_urgent",
      "isFavorited": false,
      "isArchived": false,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-10T00:00:00Z",
      "time": "2024-01-01T00:00:00Z",
      "accessCountTotal": 15,
      "accessCount7d": 3,
      "accessCount30d": 8,
      "lastAccessedAt": "2024-01-15T10:30:00Z",
      "trend": "rising",
      "recent7dAccessCount": 3,
      "previous7dAccessCount": 1,
      "valueScore": 58,
      "recommendation": {
        "action": "keep",
        "reason": "Usage, freshness, or relevance still supports keeping it active."
      }
    }
  ]
}
```

---

#### POST `/api/insights/[id]/view` - Record Insight View

```bash
curl -X POST "http://localhost:3414/api/insights/insight_xxx/view" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"viewSource": "search"}'
```

**Parameters:**
- `viewSource` (string) - Source type: `list`, `detail`, `search`, `favorite`

**Response:**
```json
{
  "ok": true
}
```

---

## CLI Script

### Quick Start

```bash
# Search ALL memory sources at once (recommended for comprehensive search)
node $SKILL_DIR/scripts/openloomi-memory.cjs search-all "query"

# Search local memory files (full-text, case-insensitive)
node $SKILL_DIR/scripts/openloomi-memory.cjs search-memory "boss"

# Search local memory files in specific subdirectory
node $SKILL_DIR/scripts/openloomi-memory.cjs search-memory "project" --directory=projects

# Search knowledge base (RAG, semantic search)
node $SKILL_DIR/scripts/openloomi-memory.cjs search-knowledge "project plan"

# List knowledge base documents
node $SKILL_DIR/scripts/openloomi-memory.cjs list-documents

# Get document content
node $SKILL_DIR/scripts/openloomi-memory.cjs get-document doc_xxx

# List recent insights (last 7 days)
node $SKILL_DIR/scripts/openloomi-memory.cjs list-insights --days=7

# List insights from a specific channel (e.g., Gmail, Telegram, WhatsApp)
node $SKILL_DIR/scripts/openloomi-memory.cjs list-insights --channel=gmail --days=7
node $SKILL_DIR/scripts/openloomi-memory.cjs list-insights --channel=telegram --days=30
node $SKILL_DIR/scripts/openloomi-memory.cjs list-insights --channel=whatsapp

# Filter insights by keyword (supports multiple keywords - OR logic)
node $SKILL_DIR/scripts/openloomi-memory.cjs list-insights --keyword=screen --keyword=linkedin --days=30

# Get single insight
node $SKILL_DIR/scripts/openloomi-memory.cjs get-insight insight_xxx

# Create a new insight
node $SKILL_DIR/scripts/openloomi-memory.cjs add-insight --title="Coffee preference" --description="I prefer Americano coffee" --importance=General

# Update an insight (partial update with array append)
node $SKILL_DIR/scripts/openloomi-memory.cjs update-insight insight_xxx --description="Updated description" --detail="User mentioned new preference"

# Delete insight
node $SKILL_DIR/scripts/openloomi-memory.cjs delete-insight insight_xxx

# Add a memory file
node $SKILL_DIR/scripts/openloomi-memory.cjs add-memory "My boss John likes Monday project discussions" --file=people/boss.md

# Delete a memory file
node $SKILL_DIR/scripts/openloomi-memory.cjs delete-memory people/boss.md
```

### Command Reference

| Command | Description | Target |
|---------|-------------|--------|
| `search-all` | Search **all** memory sources simultaneously | Local files + Knowledge base + Insights |
| `search-memory` | Full-text search in local `.md`/`.json` files | `~/.openloomi/data/memory/` |
| `search-knowledge` | Semantic search via embeddings | openloomi server (RAG) |
| `list-documents` | List uploaded documents | Knowledge base |
| `get-document` | Get document content by ID | Knowledge base |
| `list-insights` | List extracted insights (supports `--channel` filter) | Insights API |
| `get-insight` | Get single insight by ID | Insights API |
| `delete-insight` | Delete an insight | Insights API |
| `add-insight` | Create a new insight (title, description, importance, urgency, groups, people) | Insights API |
| `update-insight` | Update an insight (partial update with array append logic) | Insights API |
| `add-memory` | Add a memory file (auto-generates filename from content) | Local filesystem |
| `delete-memory` | Delete a memory file | Local filesystem |

---

## AI Agent Workflow

Triggered when the user asks about memory, knowledge, or past information:

1. Memory file search - "search my memory", "find what I said about..."
2. Knowledge base search - "search uploaded documents", "find in knowledge base"
3. Insights management - "list insights", "delete an insight"
4. **Channel insights** - "what messages on Gmail?", "show me Telegram chats", "any WhatsApp messages?"
5. **Comprehensive search** - "search everything", "find in all my memory", "build relationship graph"

**Execution Flow:**

1. **Identify intent** - determine if user wants comprehensive search or specific source
2. **Prefer `search-all`** - for general memory queries, always use `search-all` first to get comprehensive results across all sources
3. **Execute in parallel** - when specific sources are needed, run multiple searches simultaneously:
   - `search-memory` for local files
   - `search-knowledge` for uploaded documents
   - `list-insights` for extracted insights
4. **For channel queries** - use `list-insights` with `--channel` parameter:
   - `"gmail"` - Email messages via Gmail
   - `"outlook"` - Email messages via Outlook
   - `"telegram"` - Telegram chats
   - `"whatsapp"` - WhatsApp messages
   - `"slack"` - Slack messages
   - `"discord"` - Discord messages
   - `"linkedin"` - LinkedIn messages
   - `"twitter"` - Twitter/X posts
   - `"weixin"` - WeChat messages
   - `"rss"` - RSS feed items
5. **Format output** - aggregate and present results in user's language

**Best Practice for Comprehensive Queries:**

```bash
# When user asks about relationships, people, or general memory:
node $SKILL_DIR/scripts/openloomi-memory.cjs search-all "person/project/topic"

# Then optionally get details from specific sources
node $SKILL_DIR/scripts/openloomi-memory.cjs search-memory "person" --directory=people
node $SKILL_DIR/scripts/openloomi-memory.cjs list-insights --days=30 --keyword=<keyword>
```

**Channel-Based Message Queries:**

```bash
# User asks "what emails did I receive?" or "show me Gmail messages"
node $SKILL_DIR/scripts/openloomi-memory.cjs list-insights --channel=gmail --days=7

# User asks "any Telegram messages about project X"?
node $SKILL_DIR/scripts/openloomi-memory.cjs list-insights --channel=telegram --days=30

# User asks "recent WhatsApp messages"?
node $SKILL_DIR/scripts/openloomi-memory.cjs list-insights --channel=whatsapp
```

---

## Living Connections (Hebbian Potentiation)

Living Connections track relationships between insights that strengthen when they're accessed together. This implements Hebbian learning: "insights that fire together, wire together."

### Commands

```bash
# Get related insights - "users who viewed X also viewed Y"
node $SKILL_DIR/scripts/openloomi-memory.cjs get-related-insights <insightId>

# Get related insights with filters
node $SKILL_DIR/scripts/openloomi-memory.cjs get-related-insights insight_xxx --limit=10 --minStrength=0.3

# Get connection statistics
node $SKILL_DIR/scripts/openloomi-memory.cjs get-connection-stats <insightId>
```

### How It Works

1. When you view an insight, connections to other insights viewed within 5 minutes are strengthened
2. Connection strength decays over time using Ebbinghaus-style forgetting curve
3. Strong connections (strength > 0.5) are considered "living" - actively referenced

### Response Format

```json
{
  "insightId": "insight_xxx",
  "connections": [...],
  "relatedInsights": [
    {
      "insightId": "insight_yyy",
      "strength": 0.72,
      "coAccessCount": 5
    }
  ],
  "total": 5
}
```

---

## Temporal Queries (Time-Travel)

Temporal validity enables "time-travel" queries - seeing what insights were relevant at a specific point in time.

### Commands

```bash
# Get insights valid at a specific point in time (time-travel query)
node $SKILL_DIR/scripts/openloomi-memory.cjs get-insights-as-of 2026-01-01

# Get currently valid insights (no expiration or future expiration)
node $SKILL_DIR/scripts/openloomi-memory.cjs get-current-insights

# Get insights overlapping a time interval
node $SKILL_DIR/scripts/openloomi-memory.cjs get-insights-in-interval 2026-01-01 2026-06-01
```

### Use Cases

- "What did I know about Project X on March 1st?"
- "What insights were valid during my vacation last July?"
- "Show me only currently relevant insights (hide expired ones)"

---

## Entity Registry

Entity Registry tracks people, groups, concepts, projects, and companies as first-class entities with disambiguation support.

### Commands

```bash
# List all entities of a specific type
node $SKILL_DIR/scripts/openloomi-memory.cjs list-entities --type=person

# Search entities by name
node $SKILL_DIR/scripts/openloomi-memory.cjs list-entities --search=John

# Get entity details with linked insights
node $SKILL_DIR/scripts/openloomi-memory.cjs get-entity <entityId> --insights
```

### Entity Types

| Type | Description |
|------|-------------|
| `person` | People (contacts, colleagues, friends) |
| `group` | Groups (teams, organizations) |
| `concept` | Abstract concepts (ideas, methodologies) |
| `project` | Projects (initiatives, deliverables) |
| `company` | Companies (clients, vendors, employers) |

---

## Search with Connections

Combined search that returns matching insights along with their Living Connections, providing a richer context.

```bash
# Search insights and include related insights
node $SKILL_DIR/scripts/openloomi-memory.cjs search-with-connections "project deadline"

# With custom limit
node $SKILL_DIR/scripts/openloomi-memory.cjs search-with-connections "project deadline" --limit=5
```