# mnehmos.synch.mcp
[](https://www.npmjs.com/package/mnehmos-synch-mcp)
[](https://github.com/Mnehmos/mnehmos.synch.mcp/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
**Global Memory Bank for AI Agents**
An MCP server that provides persistent context synchronization for AI agents across sessions and projects.
## Features
- **Active Context** - Get/set current working state per project
- **Filing Cabinet** - Index files with summaries and metadata for fast retrieval
- **Memory Search** - Search across all indexed content
- **Spatial Map** - "PC as Rooms" folder navigation metaphor
- **Bug Tracking** - Log and resolve bugs for agent workflows
- **Lock Management** - Concurrent agent access coordination
- **Context Events** - Agent-to-agent handoff protocol
## Installation
**Prerequisites:** Node.js 18.0.0 or higher
### From NPM (Recommended)
```bash
npm install -g mnehmos-synch-mcp
```
### From Source
```bash
git clone https://github.com/Mnehmos/mnehmos.synch.mcp.git
cd mnehmos.synch.mcp
npm install
npm run build
```
## Configuration
Add to your MCP client config (Claude Desktop, Cline, etc.):
```json
{
"mcpServers": {
"mnehmos-synch-mcp": {
"command": "npx",
"args": ["mnehmos-synch-mcp"]
}
}
}
```
Or if installed globally:
```json
{
"mcpServers": {
"mnehmos-synch-mcp": {
"command": "mnehmos-synch-mcp"
}
}
}
```
## Tools
### Context Management
| Tool | Description |
|------|-------------|
| `get_active_context` | Get current summary/focus for a project |
| `set_active_context` | Update active context state |
| `list_projects` | List all projects in memory bank |
### Filing Cabinet
| Tool | Description |
|------|-------------|
| `file_to_cabinet` | Index a file with summary and metadata |
| `get_from_cabinet` | Retrieve indexed file info |
| `search_memory` | Search across all indexed content |
### Spatial Map
| Tool | Description |
|------|-------------|
| `get_spatial_map` | Get folder structure as "rooms" |
| `add_room` | Add folder to spatial map |
| `link_rooms` | Connect two folders |
### Bug Tracking
| Tool | Description |
|------|-------------|
| `log_bug` | Log a bug for later fixing |
| `get_bugs` | Get bugs by project/status |
| `resolve_bug` | Mark bug as resolved |
### Concurrent Access
| Tool | Description |
|------|-------------|
| `acquire_lock` | Lock a resource for exclusive access |
| `release_lock` | Release a held lock |
| `get_lock_status` | Check lock state |
### Agent Coordination
| Tool | Description |
|------|-------------|
| `emit_context_event` | Emit handoff/checkpoint/error events |
| `get_context_events` | Get recent context events |
### Server Configuration
| Tool | Description |
|------|-------------|
| `configure_server` | First-run setup for server location |
| `get_server_info` | Get server configuration |
## Usage
```typescript
// Set active context for a project
await client.callTool("set_active_context", {
project_id: "my-app",
summary: "Working on authentication module",
focus: "src/auth/login.ts"
});
// Index a file
await client.callTool("file_to_cabinet", {
project_id: "my-app",
file_path: "src/auth/login.ts",
summary: "Login handler with JWT validation",
key_exports: ["login", "validateToken"]
});
// Search memory
await client.callTool("search_memory", {
query: "authentication",
project_id: "my-app"
});
// Emit handoff event
await client.callTool("emit_context_event", {
project_id: "my-app",
agent_id: "agent-1",
event_type: "handoff",
summary: "Completed auth module, ready for testing"
});
```
## Data Storage
Data is stored locally in SQLite with Markdown file fallbacks:
| Platform | Location |
|----------|----------|
| **Windows** | `%USERPROFILE%\.agent-synch\` |
| **macOS/Linux** | `~/.agent-synch/` |
Storage includes:
- `agent_synch.db` - SQLite database
- `projects/{id}/` - Per-project markdown files
- `.locks/` - Lock files for crash recovery
## Development
```bash
# Install dependencies
npm install
# Development mode with watch
npm run dev
# Run tests
npm test
# Build for production
npm run build
```
## License
MIT
## Author
[Mnehmos](https://github.com/Mnehmos)
## Links
- [NPM Package](https://www.npmjs.com/package/mnehmos-synch-mcp)
- [GitHub Repository](https://github.com/Mnehmos/mnehmos.synch.mcp)
- [Changelog](https://github.com/Mnehmos/mnehmos.synch.mcp/blob/master/CHANGELOG.md)
