Skip to main content
Glama
tostechbr

MemoryClaw

by tostechbr
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

MemoryClaw

Universal Memory & Context Engine for LLMs

License: MIT Node.js Protocol

"MemoryClaw" implies a universal, infinite context for your AI.

MemoryClaw is an open-source library that adds persistent memory and intelligent context management to AI agents. Your agents can remember past conversations, decisions, and context across sessions - while automatically managing token limits.

The Vision

┌─────────────────────────────────────────────────────────────┐
│                      MEMORYCLAW                     │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Memory    │  │   Context   │  │   Session   │         │
│  │   Search    │  │  Management │  │  Lifecycle  │         │
│  │  (Phase 1)  │  │  (Phase 2)  │  │  (Phase 3)  │         │
│  │     ✅      │  │     🚧      │  │     📋      │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                             │
│  Store memories → Search intelligently → Manage limits     │
└─────────────────────────────────────────────────────────────┘

Related MCP server: BuildAutomata Memory MCP Server

Current Status: Phase 1 - Memory Search ✅ + Sprint 0 Next

What works today:

  • Store memories in Markdown files (human-readable, git-friendly)

  • Search using BM25 keyword matching

  • Full CRUD via MCP Protocol (search, get, store, delete)

  • Chunk large files for better search results

  • 140 tests passing (unit + integration + QA)

⚠️ Current limitation: No multi-user isolation. All users share the same workspace. Sprint 0 (next) will add userId parameter to all tools for per-user memory isolation.

Coming in Sprint 0: Multi-user isolation (userId per tool, per-user database)

Coming in Phase 2: Vector search (sqlite-vec, hybrid merge)

Coming in Phase 3: Context management (compaction, memory flush, pruning)

Quick Start with n8n

1. Clone and Build

git clone https://github.com/tostechbr/memory-claw.git
cd memory-claw
pnpm install
pnpm build

2. Create Your Memory Files

my-workspace/
├── MEMORY.md           # Long-term curated knowledge
└── memory/
    ├── 2026-01-31.md   # Daily notes
    ├── projects.md     # Project notes
    └── contacts.md     # Important contacts

Example MEMORY.md:

# My Memory

## About Me
I'm a developer working on AI projects.

## Current Projects
- MemoryClaw - Adding memory to AI agents
- My App - A productivity tool

## Important Contacts
- John: john@email.com - Technical mentor
- Sarah: sarah@email.com - Design partner

3. Install n8n Community Node

IMPORTANT: This integration uses the n8n-nodes-mcp community node, which must be installed separately.

In your n8n instance:

  1. Go to Settings → Community Nodes

  2. Click Install a community node

  3. Enter: n8n-nodes-mcp

  4. Click Install

  5. Restart n8n after installation

Documentation: https://www.npmjs.com/package/n8n-nodes-mcp

4. Configure MCP Server

Edit packages/mcp-server/run-server.sh to point to your workspace:

WORKSPACE="/path/to/your/my-workspace"

Create MCP Credential in n8n:

  1. Go to Credentials → Create New

  2. Search for "MCP" and select MCP API

  3. Fill in the fields:

Field

Value

Name

MemoryClaw

Command

bash

Arguments

/absolute/path/to/memory-claw/packages/mcp-server/run-server.sh

Environments

OPENAI_API_KEY=sk-your-actual-key

  1. Click Save

Important: Use the absolute path to run-server.sh. Relative paths will not work.

5. Import Working Workflow

Create a new workflow in n8n and import this JSON:

{
  "name": "MemoryClaw Memory Test",
  "nodes": [
    {
      "parameters": {
        "options": {}
      },
      "type": "@n8n/n8n-nodes-langchain.chatTrigger",
      "typeVersion": 1.1,
      "position": [460, 240],
      "id": "chat-trigger",
      "name": "When chat message received"
    },
    {
      "parameters": {
        "promptType": "define",
        "text": "={{ $json.chatInput }}",
        "options": {
          "systemMessage": "You are a personal assistant with access to the user's memory. Use the memory_search tool to find relevant information before answering questions."
        }
      },
      "type": "@n8n/n8n-nodes-langchain.agent",
      "typeVersion": 1.7,
      "position": [680, 240],
      "id": "ai-agent",
      "name": "AI Agent"
    },
    {
      "parameters": {
        "model": "gpt-4o-mini"
      },
      "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
      "typeVersion": 1,
      "position": [680, 440],
      "id": "openai-model",
      "name": "OpenAI Chat Model",
      "credentials": {
        "openAiApi": {
          "id": "your-openai-credential",
          "name": "OpenAI account"
        }
      }
    },
    {
      "parameters": {
        "operation": "executeTool",
        "toolName": "memory_search",
        "toolParameters": "{\"query\": \"{{ $json.chatInput.replace(/\\n/g, ' ').trim() }}\", \"minScore\": 0}"
      },
      "type": "n8n-nodes-mcp.mcpClientTool",
      "typeVersion": 1,
      "position": [680, 80],
      "id": "mcp-client",
      "name": "MCP Client",
      "credentials": {
        "mcpApi": {
          "id": "your-mcp-credential",
          "name": "MemoryClaw"
        }
      }
    }
  ],
  "connections": {
    "When chat message received": {
      "main": [[{ "node": "AI Agent", "type": "main", "index": 0 }]]
    },
    "OpenAI Chat Model": {
      "ai_languageModel": [[{ "node": "AI Agent", "type": "ai_languageModel", "index": 0 }]]
    },
    "MCP Client": {
      "ai_tool": [[{ "node": "AI Agent", "type": "ai_tool", "index": 0 }]]
    }
  }
}

After importing:

  1. Open the OpenAI Chat Model node and select your OpenAI credential

  2. Open the MCP Client node and select your MemoryClaw credential

  3. Save the workflow

  4. Activate the workflow (toggle in top-right)

6. Test It!

Open the workflow chat interface and ask:

  • "What projects am I working on?"

  • "Who is my technical mentor?"

  • "What did we discuss yesterday?"

Expected behavior:

  • The AI Agent will use the memory_search tool to query your memory files

  • Results will be returned from MEMORY.md and memory/*.md files

  • The agent will answer based on the search results

Troubleshooting

Problem: MCP Client node shows "Tool not found: memory_search"

Solution:

  • Check that run-server.sh has the correct absolute path to your workspace

  • Verify OPENAI_API_KEY is set in the MCP credential

  • Check n8n logs for MCP server startup errors

  • Test the MCP server directly: cd packages/mcp-server && node test-simple.js

Problem: Search returns no results

Solution:

  • Ensure MEMORY.md or memory/*.md files exist in your workspace

  • Check that the files contain text content

  • Try setting "minScore": 0 in the toolParameters to see all results

  • Rebuild the project: pnpm build

Problem: "n8n-nodes-mcp not found"

Solution:

  • The community node must be installed via n8n's UI (Settings → Community Nodes)

  • Restart n8n after installation

  • Check n8n version compatibility (requires n8n 1.0+)

Architecture

┌─────────────────────────────────────────────────────────────┐
│  AI Agent (Claude, GPT, etc.) + userId                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  MCP Server (stdio)                                         │
│  Tools: memory_search, memory_get, memory_store, memory_del │
│  + userId param → per-user isolation (Sprint 0 - planned)   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Core Library                                               │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Chunking   │  │   Storage    │  │   Search     │      │
│  │  400 tokens  │  │   SQLite     │  │  BM25 + Vec  │      │
│  │  80 overlap  │  │   + FTS5     │  │   (hybrid)   │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Memory Files (per user - planned)                          │
│  users/{userId}/MEMORY.md + memory/*.md                     │
│  users/{userId}/memory.db                                   │
└─────────────────────────────────────────────────────────────┘

Roadmap

Phase 1: Memory Search ✅ Current

Feature

Status

Description

Memory Storage

✅ Done

MEMORY.md + memory/*.md

Markdown Chunking

✅ Done

~400 tokens, 80 overlap

SQLite + FTS5

✅ Done

Keyword indexing

BM25 Search

✅ Done

Keyword matching

Embedding Cache

✅ Done

Hash-based deduplication

MCP Server

✅ Done

stdio transport, 4 tools (search, get, store, delete)

n8n Integration

✅ Done

Works with AI Agent node

Integration Tests

✅ Done

15 end-to-end tests

QA Scenarios

✅ Done

17 assertions, 4 real-user scenarios

Sprint 0: Multi-User Isolation 🎯 Next

Feature

Status

Description

userId Parameter

🎯 Planned

Add userId to all 4 MCP tools

Per-User Workspace

🎯 Planned

users/{userId}/MEMORY.md + memory/*.md

Per-User Database

🎯 Planned

users/{userId}/memory.db — total isolation

Manager Pool

🎯 Planned

LRU pool of MemoryManagers per userId

Backward Compat

🎯 Planned

No userId → defaults to "default" user

WhatsApp Workflow

🎯 Planned

n8n example with phone as userId

Phase 1.5: Memory Foundation 📋 After Sprint 0

Feature

Status

Description

sqlite-vec Extension

📋 Planned

Load vector extension

Vector Search

📋 Planned

Cosine similarity search

Hybrid Merge

📋 Planned

70% vector + 30% keyword

Embedding Batch API

📋 Planned

OpenAI Batch (50% cheaper)

Phase 2: Context Management 🚧 Planned

Feature

Status

Description

Token Counting

📋 Planned

Measure context usage

Context Window Guard

📋 Planned

Warn/block thresholds

Memory Flush

📋 Planned

Save before compaction

Compaction

📋 Planned

Summarize old conversation

Context Pruning

📋 Planned

Soft trim + hard clear

Phase 3: Session Lifecycle 📋 Future

Feature

Status

Description

Session Management

📋 Planned

Reset rules (daily, manual)

Session Transcripts

📋 Planned

JSONL storage

Session Memory Hook

📋 Planned

Auto-save on /new

Cache-TTL Pruning

📋 Planned

Anthropic cache optimization

HTTP Adapter

📋 Planned

Cloud n8n support

Available Tools

memory_search

Search your memories using keyword matching.

{
  "query": "project status",
  "maxResults": 5,
  "minScore": 0,
  "userId": "user_123"
}

Note: userId will be added in Sprint 0. Currently all tools operate on a single shared workspace.

memory_get

Read specific lines from a memory file.

{
  "path": "memory/projects.md",
  "from": 1,
  "lines": 20,
  "userId": "user_123"
}

memory_store

Create or update a memory file.

{
  "path": "memory/profile.md",
  "content": "# Profile\nName: Maria\nCompany: TechCorp",
  "userId": "user_123"
}

memory_delete

Delete a memory file.

{
  "path": "memory/old-notes.md",
  "userId": "user_123"
}

Development

# Install
pnpm install

# Build
pnpm build

# Test all packages
pnpm test

# Test MCP server only
cd packages/mcp-server
pnpm test:unit        # Unit tests (fast, recommended)
pnpm test:watch       # Watch mode for development

# Build and test MCP Server
pnpm build && pnpm test

See Testing Guide and Architecture for detailed instructions.

Current Limitations

Limitation

Reason

Planned Solution

No multi-user isolation

No userId parameter

Sprint 0: Per-user workspace + database

Keyword search only

sqlite-vec not loaded

Phase 1.5: Vector search

No compaction

Not implemented yet

Phase 2: Compaction

Local n8n only

MCP uses stdio

Phase 3: HTTP adapter

No token metrics

Not implemented yet

Phase 2: Token counting

Contributing

Contributions are welcome! We especially need help with:

  • Sprint 0: Multi-user isolation (userId per tool, per-user database)

  • Phase 1.5 features: Vector search, hybrid merge

  • Testing: Integration tests, multi-user isolation tests

  • Documentation: Usage guides and examples

  • Integrations: Claude Desktop, Cursor, WhatsApp workflows

How to Contribute

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

Project Structure

memory-claw/
├── packages/
│   ├── core/           # Core library (search, storage, chunking)
│   └── mcp-server/     # MCP Server for AI agents
├── examples/           # Example workspaces
├── docs/               # Documentation
└── test-workspace-mcp/ # Test workspace

License

MIT License - See LICENSE for details.

Credits

Architecture inspired by Moltbot, an open-source AI assistant.

Author

Tiago Santos - @tostechbr

Give your AI agents the gift of memory.

This server cannot be installed

A
license - permissive license
-
quality - not tested
-
maintenance - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tostechbr/memoryClaw'

If you have feedback or need assistance with the MCP directory API, please join our Discord server