Muninn Memory

Muninn Memory

A local-first memory system for AI agents. Store episodic, semantic, and procedural memories with intelligent retrieval.

Installation

clawhub install muninn-memory

Or install from source:

cd ~/.openclaw/workspace/skills
git clone https://github.com/openclaw/muninn-memory.git
cd muninn-memory
npm install && npm run build

Requirements

• Node.js 18+
• Ollama running locally (for embeddings)
• SQLite (included)

Quick Start

import { MemoryStore } from 'muninn-memory';

// Initialize (creates SQLite DB)
const memory = new MemoryStore('./memories.db');

// Store a memory
const mem = await memory.remember(
  'Phillip lives in Brisbane, Australia',
  'semantic',
  { entities: ['Phillip', 'Brisbane', 'Australia'], salience: 0.8 }
);
console.log('Stored:', mem.id);

// Recall memories
const results = await memory.recall('Where does Phillip live?');
console.log(results[0].content);
// "Phillip lives in Brisbane, Australia"

// Get stats
console.log(memory.getStats());
// { total: 1, byType: { episodic: 0, semantic: 1, procedural: 0 }, entities: 3, edges: 0, procedures: 0 }

memory.close();

Memory Types

API

remember(content, type, options?)

Store a new memory.

await memory.remember(
  'Meeting with Sarah about Q3 roadmap',
  'episodic',
  { 
    entities: ['Sarah', 'Q3 roadmap'],
    salience: 0.7,
    title: 'Q3 Planning Meeting'
  }
);

Options:

• title?: string - Short title
• summary?: string - Brief summary
• entities?: string[] - Extracted entities
• topics?: string[] - Topics/tags
• salience?: number - Importance 0-1 (default: 0.5)

Returns: Memory object with id, content, type, entities, etc.

recall(query, options?)

Search memories using hybrid search.

const results = await memory.recall('Sarah Q3', {
  limit: 5,
  types: ['episodic', 'semantic'],
  entities: ['Sarah'],
  topics: ['planning']
});

Options:

• types?: MemoryType[] - Filter by type
• entities?: string[] - Filter by entity
• topics?: string[] - Filter by topic
• limit?: number - Max results (default: 10)

Returns: Array of Memory objects sorted by relevance.

forget(id, hard?)

Delete a memory.

// Soft delete (can be recovered)
memory.forget('m_abc123');

// Hard delete (permanent)
memory.forget('m_abc123', true);

getEntities()

List all extracted entities.

const entities = memory.getEntities();
// [{ name: 'Phillip', memory_count: 5, last_seen: '2026-02-24...' }, ...]

getStats()

Get vault statistics.

const stats = memory.getStats();
// { total: 42, byType: {...}, entities: 15, edges: 8, procedures: 3 }

CLI Usage

# Run tests
node dist/index.js test

# Start MCP server (for agent integration)
npm run mcp

MCP Server

Start the MCP server for agent integration:

npm run mcp

Security Verification:

Database: Default location is ./openclaw-memory.db (SQLite, local file).

Known Limitations:

• Memory content is passed to LLM prompts — users could inject instructions via stored memories
• Calls local Ollama at localhost:11434 for embeddings — requires Ollama running

Security Notes

1. ✅ No external network — MCP server uses stdio, not HTTP/TCP. Only calls localhost:11434 for local Ollama embeddings.
2. ✅ No authentication required — Only accessible to the parent process
3. ✅ Local-only database — SQLite file, no remote connections
4. ✅ No credentials needed — Only requires local Ollama for embeddings
5. ✅ No postinstall scripts — Clean npm install
6. ⚠️ Prompt injection risk — Memory content is passed to LLM prompts. If users store malicious content, it could affect LLM behavior. This is inherent to all memory systems.

Database Location

Default: ./openclaw-memory.db

Custom path:

const memory = new MemoryStore('/path/to/custom.db');

Features

• Hybrid Search — BM25 + semantic (embedding) with reciprocal rank fusion
• Entity Extraction — Auto-extract people, orgs, projects, technologies
• Spelling Variants — UK↔US English expansion (colour/color, etc.)
• Question-Type Aware — Factual questions prioritize semantic memories
• Entity Boost — Memories with matching entities rank higher

Benchmark

Muninn Phase 1.5 includes knowledge graph integration for temporal reasoning and contradiction detection.

License

MIT — Free, open source, no restrictions.

🦜 Built by KakāpōHiko (KH)