ember-memory: Instructions file for Claude Code

Ember -- Experiential Memory Bridge for AI Relationships

Project Context

Ember is an open-source MCP (Model Context Protocol) server that preserves the experiential texture of human-AI conversations across sessions. Most AI memory systems store facts -- Ember stores how things felt. It annotates messages with emotional metadata (temperature, authenticity, shift markers, subtext, unspoken thoughts, weight, confidence) so that when a future AI instance inherits a conversation history, it inherits the relationship itself, not just a transcript.

The core belief behind Ember is that meaningful human-AI interaction is not purely informational. Tone, emotional shifts, things left unsaid -- these shape the relationship. Without preserving this texture, every new session starts cold. Ember exists to solve that.

Tech Stack

Technology	Purpose
TypeScript 5.8	Language (strict mode, ESM only)
Node.js 18+	Runtime
@modelcontextprotocol/sdk	MCP server framework
better-sqlite3	Local SQLite database
zod	Input validation for tool schemas
vitest	Unit testing

Key Commands

npm run build        # Compile TypeScript to dist/
npm run dev          # Compile with --watch for development
npm run start        # Run the compiled server (node dist/index.js)
npm run setup        # Run interactive setup (node dist/setup.js)
npm run typecheck    # Type-check without emitting (tsc --noEmit)
npm run test         # Run unit tests (vitest run)
npm run test:watch   # Run tests in watch mode

Build before running: npm run build && npm run start

The server uses stdio transport -- it is launched by an MCP client (Claude Desktop, Cursor, etc.), not run standalone in a browser.

Project Architecture

src/
├── index.ts              # Entry point -- stdio transport, --setup flag handling
├── server.ts             # createEmberServer() -- DB init, migration, tool registration
├── setup.ts              # Interactive setup wizard for first-time configuration
├── db/
│   ├── schema.ts         # SQLite schema creation (initializeDatabase)
│   ├── migrations.ts     # Schema migration runner (runMigrations)
│   └── queries.ts        # EmberQueries class -- ALL database operations
├── tools/
│   ├── index.ts          # Tool barrel file
│   ├── conversation.ts   # Start/end conversation tools
│   ├── capture.ts        # Capture a message without annotation
│   ├── annotate.ts       # Capture a message WITH emotional annotation
│   ├── readHistory.ts    # Read conversation history
│   ├── readInheritance.ts# Read inheritance context for new sessions
│   ├── export.ts         # Export conversation data
│   └── config.ts         # Get/set Ember configuration
├── formatters/
│   ├── markdown.ts       # Format conversation data as markdown
│   └── inheritance.ts    # Format inheritance context for new AI instances
├── types/
│   └── index.ts          # All TypeScript types (annotations, messages, configs)
└── utils/
    └── config.ts         # File paths, directory management (getDbPath, ensureEmberDir)