Openloomi Memory

Note: If OpenLoomi readiness is unknown, use openloomi-setup first. If OpenLoomi Desktop is not installed, follow 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 for the full model.

This skill exposes three searchable surfaces over that context:

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:

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:

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

{
  "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.

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:

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

GET /api/rag/documents - List Documents

List all documents in the knowledge base.

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

Parameters:

• limit (number, default 50) - Max results to return

Response:

{
  "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.

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

Response:

{
  "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.

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:

{
  "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:

Common Channel Groups:

POST /api/insights - Create Insight

Create a new insight manually.

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:

{
  "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.

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:

{
  "message": "Insight updated successfully",
  "id": "insight_xxx"
}

GET /api/insights/[id]?fetch=true - Get Insight

Get a single insight by ID, including associated chat.

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

Response:

{
  "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.

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

Response:

{
  "success": true
}

GET /api/chat-insights?chatId=xxx - Get Chat Insights

Get all insights for a specific chat.

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