mnemonio

mnemonio.com

Persistent structured memory layer for LLM agents. Mnemonio gives your agent a file-based memory system that survives across sessions -- markdown files with YAML frontmatter, a manifest file, semantic search, automatic extraction from conversations, and periodic consolidation.

It ships as an MCP server, a CLI, and a TypeScript library. LLM operations use a callback you provide, so it works with any provider.

MCP Server

The fastest way to get started. Add mnemonio to your MCP client settings and your AI coding assistant gets persistent memory automatically.

Setup

{
  "mcpServers": {
    "mnemonio": {
      "command": "npx",
      "args": ["-p", "@memel06/mnemonio", "mnemonio-mcp"],
      "env": {
        "MNEMONIO_DIR": "./.mnemonio"
      }
    }
  }
}

For LLM-dependent tools (search, extract, distill), create a .env file in your project root (and add it to .gitignore):

MNEMONIO_API_KEY=your-api-key
MNEMONIO_BASE_URL=https://your-llm-provider.com/v1
MNEMONIO_MODEL=your-model

Mnemonio loads .env automatically.

You can also pass these as env vars in the MCP config if you prefer:

{
  "mcpServers": {
    "mnemonio": {
      "command": "npx",
      "args": ["-p", "@memel06/mnemonio", "mnemonio-mcp"],
      "env": {
        "MNEMONIO_DIR": "./.mnemonio",
        "MNEMONIO_BASE_URL": "https://your-llm-provider.com/v1",
        "MNEMONIO_MODEL": "your-model"
      }
    }
  }
}

The server auto-detects the provider from the base URL:

| Base URL contains | Provider | Token param | Auth | Endpoint | |-------------------|----------|-------------|------|----------| | openai.com | OpenAI (modern) | max_completion_tokens | Bearer | /chat/completions | | anthropic.com | Anthropic | max_tokens | x-api-key | /v1/messages | | openrouter.ai | OpenRouter | max_tokens | Bearer | /chat/completions | | anything else | Generic (OpenAI-compatible) | max_tokens | Bearer | /chat/completions |

Override auto-detection with MNEMONIO_PROVIDER (in .env or MCP config):

MNEMONIO_PROVIDER=anthropic
MNEMONIO_API_KEY=sk-ant-...
MNEMONIO_BASE_URL=https://api.anthropic.com
MNEMONIO_MODEL=claude-sonnet-4-6-20250514

Valid provider values: openai, openai-classic, anthropic, openrouter.

Available Tools

| Tool | LLM needed | Team aware | Description | |------|-----------|------------|-------------| | memory_list | No | Yes | List all memories, optionally filtered by type or tags | | memory_read | No | Yes | Read full content of a memory file | | memory_save | No | No | Save a new memory with frontmatter + manifest entry | | memory_delete | No | No | Delete a memory file and remove it from the manifest | | memory_search | Yes | Yes | Semantic search across all memories, with optional tag pre-filter | | memory_extract | Yes | No | Auto-extract durable facts from a conversation | | memory_distill | Yes | No | Consolidate: merge duplicates, prune stale, tighten | | memory_stats | No | Yes | File count, size, type breakdown |

Team Memory

Team memory is a shared, read-only directory that gives every developer's agent the same baseline context -- coding standards, onboarding notes, project conventions. Commit it to your repo so the whole team shares it.

MCP Server

Set MNEMONIO_TEAM_DIR in your MCP config:

{
  "mcpServers": {
    "mnemonio": {
      "command": "npx",
      "args": ["-p", "@memel06/mnemonio", "mnemonio-mcp"],
      "env": {
        "MNEMONIO_DIR": "./.mnemonio",
        "MNEMONIO_TEAM_DIR": "./team-memory"
      }
    }
  }
}

Team memories automatically appear in memory_list, memory_read, memory_search, and memory_stats. Write operations (memory_save, memory_extract, memory_distill) only touch the private directory.

CLI

Use --team-dir with any read command:

mnemonio list .mnemonio --team-dir ./team-memory
mnemonio search "coding standards" .mnemonio --team-dir ./team-memory

Library

const store = createMnemonioStore({
  memoryDir: './.mnemonio',
  teamDir: './team-memory',
});

// Combined prompt includes both private and team memories
const prompt = await store.buildCombinedPrompt();

// Path traversal protection for team writes
const safePath = await store.validateTeamWritePath('notes.md');

Security

Path traversal attacks (symlinks, ../ segments, null bytes) are blocked by validateTeamWritePath. Use isTeamPath to check if a path falls within the team directory.

CLI

npm install -g @memel06/mnemonio

The CLI reads MNEMONIO_API_KEY from your environment for LLM-dependent commands (search, distill). It auto-detects the provider from MNEMONIO_BASE_URL (or you can set MNEMONIO_PROVIDER explicitly) and works with OpenAI, Anthropic, OpenRouter, and any OpenAI-compatible endpoint.

mnemonio init [dir]                        Create memory directory with MANIFEST.md
mnemonio scan [dir] [--team-dir <d>] [--json]               Display all memory file headers
mnemonio list [dir] [--type <t>] [--team-dir <d>] [--json]  List memories with descriptions + age
mnemonio search <query> [dir] [--team-dir <d>] [--json]     Find relevant memories (LLM required)
mnemonio distill [dir] [--force] [--json]  Run consolidation pass (LLM required)
mnemonio stats [dir] [--team-dir <d>] [--json]              File count, size, type breakdown
mnemonio prune [dir] [--max-age <days>] [--dry-run]         Remove stale/empty files

All commands default to the current directory if [dir] is omitted. Use --team-dir to include a shared team memory directory in listings, search, and stats.

Library

npm install @memel06/mnemonio

Quick Start

import { createMnemonioStore } from '@memel06/mnemonio';

const store = createMnemonioStore({
  memoryDir: './.mnemonio',
});

// Create the memory directory and MANIFEST.md if they don't exist
await store.ensureDir();

// Inject memory context into your system prompt
const memoryPrompt = await store.buildPrompt();
const systemPrompt = `You are a helpful assistant.\n\n${memoryPrompt}`;

// List all memory files
const headers = await store.scan();
console.log(store.formatManifest(headers));

// Get stats
const stats = await store.stats();
console.log(`${stats.totalFiles} files, ${stats.totalBytes} bytes`);

With an LLM (search, extraction, distillation)

The quickest way is to use the built-in resolveLlm helper, which reads MNEMONIO_API_KEY, MNEMONIO_BASE_URL, MNEMONIO_MODEL, and MNEMONIO_PROVIDER from your environment and auto-detects the provider:

import { createMnemonioStore, resolveLlm } from '@memel06/mnemonio';

const store = createMnemonioStore({
  memoryDir: './.mnemonio',
  llm: resolveLlm(),
});

Or wire up your own callback for full control:

import { createMnemonioStore, type LlmCallback } from '@memel06/mnemonio';

const llm: LlmCallback = async ({ system, messages, maxTokens }) => {
  const response = await yourClient.chat({
    model: 'your-model',
    max_tokens: maxTokens,
    system,
    messages,
  });
  return response.text;
};

const store = createMnemonioStore({
  memoryDir: './.mnemonio',
  llm,
});

// Semantic search
const results = await store.findRelevant('database testing approach');

// Extract memories from a conversation
await store.extract({
  messages: [
    { role: 'user', content: "Don't mock the database in integration tests." },
    { role: 'assistant', content: 'Understood, I will use the real database.' },
  ],
});

// Consolidate (merge duplicates, prune stale entries)
await store.distill({ force: true });

Configuration

interface MnemonioConfig {
  /** Path to the memory directory */
  memoryDir: string;

  /** Optional path to a shared team memory directory */
  teamDir?: string;

  /** LLM callback -- required for search, extract, distill */
  llm?: LlmCallback;

  /** Name of the entrypoint file (default: "MANIFEST.md") */
  entrypointName?: string;

  /** Max lines to include from MANIFEST.md in prompts (default: 200) */
  maxEntrypointLines?: number;

  /** Max bytes to include from MANIFEST.md in prompts (default: 25000) */
  maxEntrypointBytes?: number;

  /** Optional structured logger */
  logger?: (msg: string, level: 'debug' | 'info' | 'warn' | 'error') => void;
}

The LlmCallback type accepts any provider. You wire it up once:

type LlmCallback = (params: {
  system: string;
  messages: ReadonlyArray<{ role: 'user' | 'assistant'; content: string }>;
  maxTokens: number;
}) => Promise<string>;

API Reference

Methods (no LLM required)

| Method | Returns | Description | |--------|---------|-------------| | ensureDir() | Promise<void> | Create memory dir and MANIFEST.md if missing | | scan(signal?) | Promise<MemoryHeader[]> | List all memory files with frontmatter metadata | | readEntrypoint() | Promise<EntrypointTruncation> | Read MANIFEST.md with truncation info | | buildPrompt() | Promise<string> | Build memory context string for system prompts | | buildCombinedPrompt() | Promise<string> | Build prompt including team memory | | stats(signal?) | Promise<MnemonioStats> | File count, total size, type breakdown, age range | | formatManifest(headers) | string | Format headers as a human-readable manifest |

Methods (LLM required)

| Method | Returns | Description | |--------|---------|-------------| | findRelevant(query, opts?) | Promise<RelevantMemory[]> | Semantic search across memories | | extract(config) | Promise<ExtractResult> | Extract memories from a conversation | | distill(config?) | Promise<DistillResult> | Consolidate: merge duplicates, prune stale, tighten |

Lock Management

| Method | Returns | Description | |--------|---------|-------------| | readLastDistilledAt() | Promise<number> | Timestamp of last distillation | | tryAcquireLock() | Promise<number \| null> | Acquire distillation lock (null if held) | | rollbackLock(priorMtime) | Promise<void> | Restore lock mtime on failure |

Team Security

| Method | Returns | Description | |--------|---------|-------------| | validateTeamWritePath(filePath) | Promise<string> | Resolve and validate path within team dir | | isTeamPath(filePath) | boolean | Check if path is inside team directory |

Memory File Format

Each memory is a markdown file with YAML frontmatter:

---
name: testing-approach
description: Team prefers integration tests with real DB over mocks
type: directive
tags: [testing, database]
---

Always use the real database for integration tests.

> reason: A prior incident where mocked tests passed but production broke on a
> schema change.

> scope: Use test containers or a dedicated test database. Never mock
> the DB layer in integration suites.

The MANIFEST.md file in the memory directory serves as the entrypoint. It contains short one-line pointers to individual memory files. Mnemonio auto-truncates it when injecting into prompts to stay within token budgets.

Memory Types

| Type | Purpose | |------|---------| | identity | Information about the user -- role, goals, preferences, expertise | | directive | Corrections and confirmed approaches -- behavioral guidance | | context | Ongoing work, decisions, timelines, incidents | | bookmark | Pointers to external systems, docs, dashboards, resources |

Extended Frontmatter

| Field | Required | Description | |-------|----------|-------------| | name | No | Human-readable slug for the memory | | description | No | One-line summary shown in listings and manifests | | type | No | identity, directive, context, or bookmark | | tags | No | Freeform labels for cross-cutting concerns | | expires | No | ISO date after which this memory is automatically excluded from all operations |

License

MIT