Magneto Context System

A local context management system for AI agents and developers, built as an MCP (Model Context Protocol) server. Store, search, and retrieve markdown documents that AI tools like Cursor and Claude can access.

Features

• 📁 Hierarchical Document Storage - Organize documents in folders under ~/.magneto/documents/
• 🔍 Full-Text Search - Fast, simple text-based search across all documents
• 🧠 Semantic Search - Optional AI-powered search using OpenAI embeddings
• 🤖 MCP Integration - Works seamlessly with Cursor, Claude, and other MCP-compatible tools
• 💾 Local Storage - All data stays on your machine in ~/.magneto/
• 📝 Markdown Support - Rich text with optional YAML frontmatter metadata
• 🎯 Plan File Storage - Save and search through development plans

Installation

For Users

If you want to use Magneto in your project:

# No installation needed! Use npx
npx magneto-mcp

Configure in Cursor (see Configuration section below).

For Development

If you want to contribute or run from source:

# Clone and install dependencies
git clone https://github.com/your-username/magneto-mcp.git
cd magneto-mcp
bun install

Quick Start

1. Test the Server Locally (Development)

bun run index.ts

The server will:

• Create ~/.magneto/documents/ for your documents
• Create ~/.magneto/embeddings/ for semantic search cache
• Create ~/.magneto/config.json with default configuration
• Start the MCP server on stdio

2. Configure with Cursor

Add to your Cursor MCP configuration file at: ~/Library/Application Support/Cursor/User/globalStorage/mcp.json

{
  "mcpServers": {
    "magneto": {
      "command": "npx",
      "args": ["-y", "magneto-mcp"]
    }
  }
}

That's it! No environment variables needed. Magneto will automatically detect your git repository.

3. Configure Your First Project

When you first use Magneto in a repository, you'll need to configure a project name:

1. Open Cursor in a git repository
2. Ask the AI: "Configure this project with name 'my-project'"
3. The AI will use Magneto's configure-project tool to set it up

That's it! All future Magneto commands in that repository will use this project name automatically.

Working Across Multiple Repositories

Magneto is designed to work seamlessly across multiple repositories! When you switch to a different repo:

1. First time in a new repo: The AI will prompt you to configure a project name
2. AI handles workspace detection: The AI automatically provides your workspace path to Magneto
3. No config changes needed: Same MCP config works for all your projects

If the AI can't detect your workspace, you'll see an error like:

Cannot use Magneto: Not in a git repository.
Detected directory: /some/wrong/path

The AI will automatically:

1. Ask you for the correct project path
2. Retry the command with the workingDirectory parameter

Or if running from source during development:

{
  "mcpServers": {
    "magneto": {
      "command": "bun",
      "args": ["run", "~/path/to/magneto-mcp/index.ts"],
      "cwd": "~/path/to/magneto-mcp"
    }
  }
}

Restart Cursor, and Magneto will be available to your AI assistant!

4. Add to AGENTS.md (Recommended)

To make AI assistants automatically use Magneto for documentation, add this to your project's AGENTS.md:

## Documentation in Magneto

**Always use Magneto MCP for documentation tasks.**

When working on this codebase:
1. Before making changes: Search Magneto for existing docs
2. After making changes: Update Magneto documentation  
3. For questions: Reference Magneto when answering

**Rule**: After any significant code change, update relevant docs in Magneto automatically.

See AGENTS-INSTRUCTIONS.md for the complete copy-paste block.

5. (Optional) Enable Semantic Search

Edit ~/.magneto/config.json:

{
  "semanticSearch": {
    "enabled": true,
    "provider": "openai",
    "apiKey": "sk-your-api-key-here",
    "model": "text-embedding-3-small"
  }
}

Usage

Available MCP Tools

Once configured, your AI assistant can use these tools:

read-document

Read a specific document from your context system.

{
  "path": "projects/magneto.md"
}

write-document

Create or update a document. Automatically creates parent directories.

{
  "path": "notes/ideas/new-feature.md",
  "content": "# New Feature\n\nDetailed description..."
}

list-documents

List documents in a folder or all documents.

{
  "folderPath": "plans",  // optional
  "recursive": true        // optional
}

search-documents

Search across all documents with full-text or semantic search.

{
  "query": "authentication setup",
  "useSemanticSearch": true,  // optional, requires config
  "limit": 10                 // optional
}

delete-document

Delete a document from the system.

{
  "path": "old/deprecated.md"
}

save-current-plan

Save a plan file from your workspace to Magneto.

{
  "planFilePath": "/path/to/workspace/plan.md",
  "targetPath": "plans/magneto/2025-10-21.md"  // optional
}

Example Interactions with AI

Store context:

"Save this to my context system: [write-document with path 'projects/magneto-features.md']"

Retrieve context:

"What do I have in my context about authentication?" AI uses search-documents with query "authentication"

Organize plans:

"Save this plan to my context system" AI uses save-current-plan to store it

Reference documents:

"Check my notes on the API design" AI uses search-documents or list-documents to find relevant files

Document Organization

Suggested folder structure in ~/.magneto/documents/:

documents/
├── plans/              # Development plans
│   ├── magneto/
│   └── other-projects/
├── notes/              # General notes
│   ├── ideas/
│   └── research/
├── docs/               # Technical documentation
│   ├── apis/
│   └── architecture/
└── references/         # Reference materials

You can organize documents however you like - Magneto supports arbitrary nested folders.

Document Format

Documents are standard Markdown with optional YAML frontmatter:

---
title: My Document
tags: [ai, context, system]
created: 2025-10-21
---

# My Document

Your markdown content here...

Search Types

Full-Text Search (Default)

• Fast, simple string matching
• Returns excerpts with surrounding context
• Works offline, no API required
• Best for finding specific terms or phrases

Semantic Search (Optional)

• AI-powered understanding of intent
• Finds conceptually related documents
• Requires OpenAI API key
• Falls back to full-text if unavailable
• Best for conceptual queries like "how do I set up authentication?"

Resources

Magneto also exposes documents as MCP resources:

• URI pattern: magneto://document/{path}
• AI can reference documents directly in conversations
• Auto-listed when AI asks about available resources

Development

# Run in development
bun run dev

# Start the server
bun run start

Configuration

Configuration file: ~/.magneto/config.json

{
  "semanticSearch": {
    "enabled": false,
    "provider": "openai",
    "apiKey": "",
    "model": "text-embedding-3-small"
  }
}

Architecture

• index.ts - Entry point, initializes and starts server
• src/server.ts - MCP server implementation with tools and resources
• src/storage.ts - File system operations for documents
• src/search.ts - Full-text and semantic search implementation
• src/embeddings.ts - Embedding generation and caching
• src/config.ts - Configuration management
• src/types.ts - TypeScript type definitions

Why Magneto?

Traditional approaches like AGENTS.md are:

• Static (can't be queried dynamically)
• Repository-specific (not available across projects)
• Manual (requires copy-paste)

Magneto is:

• Dynamic (AI can search and filter on demand)
• Global (works across all conversations and projects)
• Automatic (AI reads/writes as needed)
• Semantic (optional AI-powered understanding)

License

MIT

Contributing

Issues and PRs welcome! This is a minimal implementation focused on core functionality.