# mnehmos.synch.mcp - Agent Instructions
## Quick Reference
| Property | Value |
|----------|-------|
| **Type** | MCP Server |
| **Purpose** | Global Memory Bank for AI Agents |
| **Entry Point** | `src/index.ts` |
| **Storage** | SQLite + Markdown dual-write |
| **Tools** | 21 exposed via MCP protocol |
## Architecture
```
src/
├── index.ts # MCP server, tool definitions, handlers
├── storage.ts # SQLite storage engine with MD fallback
└── lock-manager.ts # Concurrent access coordination
```
## Key Patterns
### Database is Intelligence
All state is externalized to SQLite. The agent reconstructs context from queries:
```typescript
const context = await storage.getActiveContext(projectId);
const events = await storage.getContextEvents(projectId, 5);
```
### Dual-Write for Handoff
Every context update writes to both SQLite (for queries) and Markdown (for human reading):
- `active_context.md` - Current project state
- `events/*.md` - Event history for agent handoff
### Lock Manager
For multi-agent scenarios, use locks before modifying shared resources:
```typescript
await lockManager.acquireLock(resourceId, agentId, 'write');
// ... do work ...
await lockManager.releaseLock(resourceId, agentId);
```
## Development Commands
```bash
npm run dev # Watch mode with tsx
npm run build # Compile TypeScript
npm run test # Run tests (watch)
npm run test:run # Run tests once
npm start # Run compiled server
```
## Testing
Tests use temporary directories and clean up after themselves:
```bash
npm run test:run # Run all tests
```
Coverage areas:
- Storage operations (CRUD, search, spatial map)
- Lock manager (acquire, release, queue, timeout)
## Storage Location
Runtime data stored at:
- **Windows**: `%USERPROFILE%\.agent-synch\`
- **Unix**: `~/.agent-synch/`
Contents:
- `agent_synch.db` - SQLite database
- `projects/{id}/` - Per-project context and events
- `.locks/` - Lock files for crash recovery
## Tool Categories
| Category | Tools |
|----------|-------|
| Context | `get_active_context`, `set_active_context` |
| Filing | `file_to_cabinet`, `get_from_cabinet`, `search_memory` |
| Spatial | `get_spatial_map`, `add_room`, `link_rooms` |
| Bugs | `log_bug`, `get_bugs`, `resolve_bug` |
| Locks | `acquire_lock`, `release_lock`, `get_lock_status` |
| Events | `emit_context_event`, `get_context_events` |
| Admin | `configure_server`, `get_server_info`, `list_projects` |
## Common Tasks
### Adding a New Tool
1. Add tool definition to `ListToolsRequestSchema` handler in `index.ts`
2. Add handler case in `CallToolRequestSchema` handler
3. Implement storage method in `storage.ts` if needed
4. Add tests in `storage.test.ts`
### Modifying Schema
SQLite schema is in `storage.ts` `initialize()` method. Changes require migration logic for existing databases.
## Git Discipline
Follow conventional commits:
```
feat(storage): add new search capability
fix(locks): handle timeout edge case
test(storage): add bug tracking tests
```
Commit after every green test (Git Pulse rule).
