mycelicmemory

README

MyclicMemory

AI-powered persistent memory system for Claude and other AI agents

Installation • Connect to Claude • Features • AI Features

---

MyclicMemory gives Claude persistent memory across conversations. Store knowledge, search semantically, and get AI-powered insights from your memories.

Free and open source - no license keys, no subscriptions.

---

Installation

Prerequisites

Required:

• Node.js 18+ (includes npm)

Optional (for enhanced AI features):

• Ollama - For semantic search and AI analysis

Install via npm

npm install -g mycelicmemory

Important: After installation, run mycelicmemory once to download the platform-specific binary:

mycelicmemory --version

The first run automatically downloads and caches the binary for your system (macOS, Linux, or Windows).

Alternative: Install from GitHub

npm install -g github:MycelicMemory/mycelicmemory

Verify Installation

mycelicmemory --version    # Should show version
mycelicmemory doctor       # Check system dependencies

---

Connect to Claude

Claude Code (CLI)

Edit ~/.claude/mcp.json:

{
  "mcpServers": {
    "mycelicmemory": {
      "command": "mycelicmemory",
      "args": ["--mcp"]
    }
  }
}

Restart Claude Code:

claude

Claude Desktop

Edit your config file:

Platform	Location
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Add:

{
  "mcpServers": {
    "mycelicmemory": {
      "command": "mycelicmemory",
      "args": ["--mcp"]
    }
  }
}

Restart Claude Desktop.

Test It Works

Ask Claude:

• "Remember that mycelicmemory is now working"
• "What memories do I have?"

---

Features

Memory Operations

Tool	Description
store_memory	Save memories with importance (1-10), tags, and domain
search	Semantic, keyword, tag, or hybrid search
get_memory_by_id	Retrieve specific memory by UUID
update_memory	Modify content, importance, or tags
delete_memory	Remove a memory permanently

AI Analysis (requires Ollama)

Tool	Description
analysis(question)	Ask natural language questions about your memories
analysis(summarize)	Generate summaries across timeframes
analysis(analyze)	Detect patterns and themes

Knowledge Organization

Tool	Description
relationships	Create/discover connections between memories
categories	Organize memories hierarchically
domains	Group by knowledge domain
sessions	Track memories by session

---

Optional: AI Features

MyclicMemory works without AI services, but semantic search and AI-powered analysis require Ollama.

Install Ollama

macOS:

brew install ollama
ollama serve

Linux:

curl -fsSL https://ollama.ai/install.sh | sh
ollama serve

Windows: Download from ollama.ai

Download Models

ollama pull nomic-embed-text   # For semantic search
ollama pull qwen2.5:3b         # For AI analysis

Verify

mycelicmemory doctor
# Should show: Ollama: Available

---

CLI Usage

MyclicMemory also works as a standalone CLI:

# Store memories
mycelicmemory remember "Go interfaces are satisfied implicitly"
mycelicmemory remember "Important!" --importance 9 --tags learning,go

# Search
mycelicmemory search "concurrency patterns"

# AI analysis (requires Ollama)
mycelicmemory analyze "What have I learned about testing?"

# Service management
mycelicmemory start    # Start REST API daemon
mycelicmemory stop     # Stop daemon
mycelicmemory doctor   # Health check

---

Configuration

Config file: ~/.mycelicmemory/config.yaml

database:
  path: ~/.mycelicmemory/memories.db

rest_api:
  port: 3099
  host: localhost

ollama:
  enabled: true
  base_url: http://localhost:11434
  embedding_model: nomic-embed-text
  chat_model: qwen2.5:3b

---

Build from Source

If you prefer to build from source (requires Go 1.23+ and a C compiler):

git clone https://github.com/MycelicMemory/mycelicmemory.git
cd mycelicmemory
make deps && make build && make install

See CONTRIBUTING.md for development setup.

---

Troubleshooting

"command not found: mycelicmemory"

Ensure npm global bin is in your PATH:

npm bin -g
# Add this directory to your PATH

MCP Not Available in Claude

# Verify installation
which mycelicmemory
mycelicmemory --version

# Test MCP mode
echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | mycelicmemory --mcp

# Validate config
cat ~/.claude/mcp.json | python3 -m json.tool

macOS Security Warning

If macOS blocks the binary:

1. Go to System Preferences > Security & Privacy > General
2. Click "Allow Anyway" next to the mycelicmemory message

Full Diagnostics

mycelicmemory doctor

---

Documentation

• Quick Start Guide
• Use Cases - 15 detailed examples
• Hooks Setup - Automatic memory capture
• Contributing

---

License

MIT License - Free and open source.

---

Links

• Repository: github.com/MycelicMemory/mycelicmemory
• Issues: GitHub Issues
• npm: npmjs.com/package/mycelicmemory