tech-memory-mcp: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents when working with this codebase.

Project Overview

tech-memory-mcp is a Model Context Protocol (MCP) Server that provides long-term technical knowledge memory for AI agents. It extracts, stores, and retrieves technical knowledge from conversations using vector embeddings and SQLite.

Core purpose: Enable AI assistants to remember "what was learned" across conversations, not just "what was said".

Tech Stack

• Runtime: Node.js >= 18.0.0 (uses better-sqlite3)
• Language: TypeScript (strict mode, ES2022 target, NodeNext modules)
• Database: SQLite with FTS5 full-text search
• Embeddings: Transformers.js with Xenova/jina-embeddings-v2-base-zh (768-dim vectors)
• MCP SDK: @modelcontextprotocol/sdk for MCP protocol implementation
• Build: TypeScript compiler (tsc), no bundler

Architecture

src/
├── index.ts              # MCP server entry point, registers all tools
├── db.ts                 # Database initialization, migrations, CRUD operations
├── embeddings.ts         # Vector embedding pipeline (Transformers.js)
├── types.ts              # Core type definitions
└── tools/                # MCP tool implementations
    ├── search.ts         # tech_search (hybrid vector + FTS search)
    ├── store.ts          # tech_store (store with semantic dedup)
    ├── auto_extract.ts   # tech_auto_extract (two-phase extraction)
    ├── extract.ts        # tech_extract_template (extraction prompt)
    ├── get.ts            # tech_get (retrieve single entry + graph neighbors)
    ├── link.ts           # tech_link (create knowledge relationships)
    ├── confirm.ts        # tech_confirm (adjust confidence)
    ├── decay.ts          # tech_decay (age-based confidence decay)
    ├── outdated.ts       # tech_outdated (query expired entries)
    └── stats.ts          # tech_stats (database statistics)

Key Patterns

Adding a New MCP Tool

1. Create src/tools/<tool_name>.ts
2. Export a register<ToolName>Tool(server: McpServer, db: DatabaseSync) function
3. Use server.registerTool() with:
   • description: Chinese description explaining what the tool does
   • inputSchema: Zod schema with .strict() to reject unknown fields
   • Handler: async function returning { content: [{ type: "text", text: string }] }
4. Register the tool in src/index.ts by calling the register function
5. All logging goes to process.stderr (stdout is reserved for MCP JSON-RPC)