Algiras/memory-wiki

Memory Wiki MCP Server

A semantic knowledge base with graph relations, powered by local embeddings. Built with Rust for high performance and low memory usage.

Features

Core

• Semantic Search: Vector embeddings with fastembed (ONNX-based, runs locally)
• Graph Relations: Link entries with typed relations (references, depends_on, etc.)
• Collections: Organize entries into collections
• Persistence: All data stored locally in JSON files
• Multi-Root Storage: Per-workspace isolation with separate data stores

Search

• Hybrid Search: Combines semantic similarity with BM25 keyword matching
• Time-Based Search: Natural language queries like "yesterday", "last week"
• Reranking: Optional cross-encoder for improved accuracy
• HyDE: Hypothetical Document Embeddings for better retrieval
• Chain-of-Thought Retrieval: Multi-step reasoning with iterative retrieval

Advanced Retrieval (NEW!)

• Multi-Perspective Exploration: GraphRAG, RAPTOR-style hierarchical retrieval
  • temporal - How knowledge evolved over time
  • relational - Graph-based multi-hop connections
  • hierarchical - Abstract concepts to specific details
  • entity - Focus on mentioned entities
  • contextual - Group by themes/collections
  • summary - CAG-powered hierarchical summaries
  • hyde - Hypothetical Document Embeddings
  • reason - Chain-of-Thought retrieval
  • reflect - Self-reflection & memory consolidation
• CAG Engine: Context-Augmented Generation with cached summaries
• Self-Reflection: Memory consolidation and gap analysis

Analysis

• Entity Extraction: Automatically detect people, technologies, concepts
• Auto-Tagging: Tag entries based on extracted entities
• Duplicate Detection: Find similar/duplicate entries
• Entry Merging: Consolidate duplicate information

Ingestion

• Document Ingestion: Smart chunking for markdown, code, and text files
• File Scheduler: Track and auto-update files on changes
• Git Metadata: Automatically capture git branch, commit, and file context
• Startup Indexing: Automatically index directories via environment variables
• Background Indexing: Async directory scanning with progress tracking
• LLM-Powered Indexing: Optional LLM analysis for summaries, entities, relationships

Web UI (NEW!)

• Knowledge Graph Visualization: Interactive D3.js graph with zoom/pan
• Perspectives Panel: Explore memories from different angles
• Search Interface: Semantic, hybrid, and time-based search
• Entry Management: Create, edit, delete entries
• Real-time Stats: Dashboard with knowledge base metrics

Installation

From crates.io

cargo install memory-wiki

From source

git clone https://github.com/Algiras/memory-wiki
cd memory-wiki/memory-wiki
cargo build --release

With LLM support

cargo build --release --features llm

Configuration

Copy .env.example to .env and customize:

# Key settings
MEMORY_WIKI_DATA_DIR=data
MEMORY_WIKI_MODEL=bge-small-en-v1.5
MEMORY_WIKI_INDEX_DIRS=/path/to/notes,/path/to/docs
MEMORY_WIKI_ENABLE_RERANKER=true

See .env.example for all options.

Environment Variables

Core Configuration

Indexing & Processing

LLM Configuration (for background indexing)

Feature Flags

Multi-Root Storage

Usage

MCP Mode (for Claude Desktop, Cursor, etc.)

./target/release/memory-wiki

Add to your MCP client config:

{
  "mcpServers": {
    "memory-wiki": {
      "command": "/path/to/memory-wiki",
      "args": []
    }
  }
}

Web UI Mode

./target/release/memory-wiki --web --port 3001

Then open http://localhost:3001

API Overview

Memory Wiki exposes a set of Simplified Tools designed for easy interaction with LLMs. For detailed documentation, see .

Core Tools

File & Analysis Tools

Web API Endpoints

New Features

Multi-Perspective Exploration

Explore your knowledge base from different angles using the perspective tool:

{
  "tool": "perspective",
  "arguments": {
    "mode": "relational",
    "query": "machine learning",
    "depth": 2
  }
}

Available modes:

• temporal: Track knowledge evolution over time
• relational: GraphRAG-style multi-hop exploration
• hierarchical: RAPTOR-style abstraction levels
• entity: Focus on specific entities
• contextual: Group by themes
• summary: CAG-powered summaries
• hyde: Hypothetical Document Embeddings
• reason: Chain-of-Thought retrieval
• reflect: Self-reflection analysis

Background Indexing with LLM

Index directories with optional LLM-powered analysis:

curl -X POST http://localhost:3001/api/index/start \
  -H "Content-Type: application/json" \
  -d '{
    "directory": "/path/to/docs",
    "patterns": ["*.md", "*.rs"],
    "enable_llm": true,
    "build_graph": true
  }'

LLM analysis extracts:

• Summaries at multiple abstraction levels
• Entities (people, organizations, concepts)
• Topics and key points
• Relationships between documents
• Auto-generated tags

Git Metadata Integration

When storing entries from files in git repositories, Memory Wiki automatically captures:

• Branch name
• Commit hash (short and full)
• File path relative to repo root
• Repository name and remote URL
• Author and commit timestamp

Disable with MEMORY_WIKI_DISABLE_GIT_METADATA=true.

Multi-Root Storage

Memory Wiki can isolate storage per workspace root:

• Each MCP client root gets its own data store
• Use stores tool to list, switch, or enable global search
• Prevents cross-project data contamination

Search Reranking

When enabled, search results are reranked using BGE cross-encoder:

• Improves relevance for both semantic and hybrid search
• Response includes "reranked": true indicator
• Enable with MEMORY_WIKI_ENABLE_RERANKER=true

Documentation

Full documentation is available in the docs/ directory:

Available Embedding Models

Project Structure

src/
├── main.rs               # Entry point
├── config.rs             # Environment configuration
├── handler_simplified.rs # MCP request handler
├── tools/                # Tool definitions
│   ├── mod.rs            # Tool registry
│   └── simplified.rs     # Simplified tool schemas
├── handlers/             # Tool handlers
│   ├── memory.rs         # Entry management
│   ├── search.rs         # Search operations
│   ├── graph.rs          # Graph operations
│   ├── perspective.rs    # Multi-perspective exploration
│   └── ...
├── embeddings.rs         # Embedding model wrapper
├── storage_embedded.rs   # Entry storage
├── graph.rs              # Graph storage
├── multi_store.rs        # Multi-root storage manager
├── git_metadata.rs       # Git metadata extraction
├── scheduler.rs          # File scheduler
├── reranker.rs           # Cross-encoder reranking
├── ingestion.rs          # Document ingestion engine
├── consolidation.rs      # Duplicate detection
├── time_parser.rs        # Natural language time parsing
├── hybrid_search.rs      # BM25 + vector search
├── entity.rs             # Entity extraction
├── cag.rs                # Context-Augmented Generation
├── advanced_retrieval.rs # HyDE, CoT, Self-Reflection
├── background_indexer.rs # Async directory indexing
├── llm_indexer.rs        # LLM-powered analysis
├── web.rs                # Web UI server
└── models.rs             # Data structures

Data Storage

All data is stored in the data/ directory:

data/
├── entries.json         # Knowledge entries with embeddings
├── graph.json           # Relations between entries
├── scheduler.json       # File tracking state
├── collections/         # Collection metadata
└── roots/               # Per-workspace root stores (when multi-root enabled)
    └── <hash>/
        ├── entries.json
        └── graph.json

License

MIT