edumem-mcp

Directory-scoped agent memory using markdown files — an MCP server that gives LLM agents persistent, per-project memory without cluttering their context.

Why edumem-mcp?

Agents forget everything between sessions. Dumping all memories into the context is messy and doesn't scale. edumem-mcp solves this by:

• Scoping memory by directory — The agent only sees memories relevant to the workspace it's working in.

• Using plain Markdown files — Human-readable, git-friendly, easy to edit or browse manually.

• Supporting shared, read-only memories — Configure --self-mem directories with global notes, coding conventions, or project knowledge that appear alongside workspace memories.

• Zero enforced structure — Write any markdown you want; no schemas, no templates, no restrictions.

Related MCP server: mem-persistence

Installation

Note: This package is not yet published to npm. Install directly from the git repository:

Install globally from git

npm install -g github:SkillfulElectro/edumem-mcp

Or run with npx (no install)

npx -y github:SkillfulElectro/edumem-mcp

Clone and build locally

git clone https://github.com/SkillfulElectro/edumem-mcp.git
cd edumem-mcp
npm install
npm run build

Configuration

Add to your MCP client config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "edumem-mcp": {
      "command": "npx",
      "args": ["-y", "github:SkillfulElectro/edumem-mcp"]
    }
  }
}

⚠️ Important: Do NOT use npm start

When running via an MCP client config, the server communicates over stdin/stdout using JSON-RPC. npm start prints lifecycle banners to stdout (like > edumem-mcp@1.0.0 start), which break the JSON-RPC protocol. Always launch the server directly:

{
  "mcpServers": {
    "edumem-mcp": {
      "command": "npx",
      "args": ["-y", "github:SkillfulElectro/edumem-mcp"]
    }
  }
}

Or if running from a local clone:

{
  "mcpServers": {
    "edumem-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/edumem-mcp/dist/index.js"]
    }
  }
}

CLI Options

Example with custom options:

{
  "mcpServers": {
    "edumem-mcp": {
      "command": "npx",
      "args": [
        "-y", "github:SkillfulElectro/edumem-mcp",
        "--wname", ".myproject-memory",
        "--self-mem", "/Users/alex/global-notes,/Users/alex/team-conventions",
        "--workspace", "/Users/alex/projects/myapp"
      ]
    }
  }
}

How It Works

For any workspace_path the agent is working in, edumem-mcp looks for memory files in:

1. Workspace memory: <workspace_path>/.edumem-mcp/*.md (read/write by the agent)

2. Self-mem directories: Any directories passed via --self-mem (read-only by the agent)

The agent can list, read, write, delete, and search across all sources seamlessly.

Tools

list_memories

List all .md memory files visible from a workspace.

Returns an array of { name, source, size } objects.

read_memory

Read the full content of a memory file by name.

Looks in workspace memory first, then self-mem directories. Returns the raw markdown content.

search_memories

Search across all memory files for a query string (case-insensitive).

Returns an array of { name, source, snippet, line } objects.

write_memory

Create or update a memory file. Only writes to the workspace's own memory directory; cannot modify self-mem files.

delete_memory

Delete a memory file from the workspace. Cannot delete self-mem files.

Usage Examples

Agent writes a project decision

Tool: write_memory
Args: {
  "workspace_path": "/home/alex/projects/myapp",
  "memory_name": "decisions/why-postgres",
  "content": "## Why PostgreSQL\n\nChose PostgreSQL over MySQL for:\n- Better JSON support\n- Stronger ACID compliance\n- Familiar team experience"
}
Result: Memory "decisions/why-postgres.md" written successfully.

Agent recalls past decisions

Tool: list_memories
Args: { "workspace_path": "/home/alex/projects/myapp" }
Result: [
  { "name": "decisions/why-postgres.md", "source": "workspace", "size": 156 },
  { "name": "setup-notes.md", "source": "workspace", "size": 89 }
]

Tool: read_memory
Args: { "workspace_path": "/home/alex/projects/myapp", "memory_name": "decisions/why-postgres.md" }
Result: ## Why PostgreSQL ...

Agent searches for anything about "auth"

Tool: search_memories
Args: { "workspace_path": "/home/alex/projects/myapp", "query": "auth" }
Result: [
  "[workspace] setup-notes.md:12 — Configured OAuth2 with Google and GitHub",
  "[/Users/alex/global-notes] conventions.md:5 — All services must use the auth-gateway"
]

Architecture

edumem-mcp/
├── src/
│   ├── index.ts           # Entry point: CLI parsing, MCP server, stdio transport
│   ├── memory-service.ts  # Core logic: file I/O, path security, source resolution
│   └── tools.ts           # MCP tool registrations with Zod schemas
├── dist/                  # Compiled JavaScript (published to npm)
├── package.json
├── tsconfig.json
└── README.md

Security

• All file operations are restricted to allowed memory directories.

• Path traversal attacks (e.g. ../../../etc/passwd) are blocked.

• Self-mem directories are read-only — the agent cannot modify or delete them.

• Only .md files are returned by list/search; other files are ignored.

Development

git clone https://github.com/SkillfulElectro/edumem-mcp.git
cd edumem-mcp
npm install
npm run build          # compile TypeScript
npm start              # run the compiled server
# or for dev:
npm run dev            # run directly with ts-node

Testing

# Manual stdio test
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js

License

MIT