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:

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:

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:

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.

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

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

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

Response:

{
  "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": "[email protected]",
      "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

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:

{
  "ok": true
}

---

CLI Script

Quick Start

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

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

# 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

# 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

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

# 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

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

# 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