{
  "name": "aifp-mcp",
  "version": "1.5.3",
  "description": "AiFP Cognitive Memory — persistent memory MCP server for AI assistants. Chinese-first retrieval with causal chains, Hebbian associations and graph diffusion. 记忆感知系统",
  "license": "SEE LICENSE IN LICENSE",
  "type": "module",
  "main": "dist/index.js",
  "bin": {
    "aifp-mcp": "dist/index.js"
  },
  "scripts": {
    "start": "tsx src/index.ts",
    "server": "tsx src/server.ts",
    "build": "tsc",
    "prepublishOnly": "tsc",
    "postinstall": "node scripts/postinstall.mjs",
    "build:server": "tsc -p tsconfig.server.json",
    "start:server": "node dist-server/server.js"
  },
  "publishConfig": {
    "access": "public"
  },
  "files": [
    "dist/",
    "scripts/",
    "hooks/",
    "rules/",
    "README.md",
    "LICENSE",
    "package.json"
  ],
  "dependencies": {
    "@anthropic-ai/sdk": "^0.39.0",
    "@modelcontextprotocol/sdk": "^1.29.0",
    "@xenova/transformers": "^2.17.2"
  },
  "optionalDependencies": {
    "pinyin-pro": "^3.26.0"
  },
  "devDependencies": {
    "@types/node": "^26.0.1",
    "tsx": "^4.0.0",
    "typescript": "^6.0.3"
  },
  "engines": {
    "node": ">=22.0.0"
  },
  "keywords": [
    "mcp",
    "mcp-server",
    "memory",
    "cognitive",
    "memory-system",
    "perception",
    "ai",
    "agent",
    "claude-code",
    "cursor",
    "sqlite",
    "fts5",
    "vector",
    "embeddings",
    "chinese",
    "rag",
    "long-term-memory"
  ],
  "readme": "# AiFP Cognitive Memory — MCP Server\n\nPersistent memory for AI coding assistants via the [Model Context Protocol](https://modelcontextprotocol.io/).\n\n[中文文档](./README.zh.md) · [npm](https://www.npmjs.com/package/aifp-mcp)\n\nAiFP gives Obsidian, Claude Code, Cursor, Codex, DeepSeek Harness, and any other MCP-capable tool a **continuous memory that survives sessions**. It runs fully locally — your data never leaves your machine (default `~/.ai-cognition/`).\n\n## Why AiFP — a brain, not a file cabinet — one shared memory for all your desktop agents\n\nMost AI memory systems just **store** — a file cabinet you search. AiFP is built to **perceive, connect, and forget like a brain**:\n\n| Concept | What it does | Real capability |\n|---------|-------------|-----------------|\n| 🧠 **Hippocampus · perception** | New info is judged before it's stored | `observe_turn` → auto-recognizer decides what's worth remembering |\n| 👃 **Olfactory cortex · retrieval** | Find it even when you misspell it | Dual-path search: CJK FTS5 + `bge-small-zh` vector. Say \"拍森\", find Python |\n| 🗣 **Language cortex · understanding** | Understand what you meant, not just matched | Typo correction + disambiguation + Chinese time parsing (\"上个月\" → exact date) |\n| 🔗 **Synapses · perception chain** | Connect related info automatically | 6 causal relations (BECAUSE_OF / LEADS_TO / PREVENTS / ENABLES / RESPONSE_TO / CO_OCCURS_WITH) |\n| ⚡ **Hebbian neurons · association** | Neurons that fire together wire together | Co-occurrence matrix: ask about A, surface B |\n| 🌊 **Neural diffusion · recall** | Multi-hop discovery of indirect knowledge | BFS graph diffusion along the perception chain |\n| 🧬 **Synaptic consolidation · reinforcement** | The more you use it, the more important it becomes | Tier promotion: scratch → episodic → internalized → growth |\n| ⏳ **Forgetting curve** | Stale memories naturally decay | Time-based demotion & archival — the memory base never becomes a dump |\n| 📊 **Neural signal · confidence** | Every memory carries a trust signal | Confidence scoring, high-confidence surfaces first |\n| 👤 **Owner cognition model · profile** | Understands *you* — preferences, habits, facts | Preference/fact accumulation; AI suggestions are never mixed into your profile |\n| 💪 **Muscle memory · cross-turn** | Done work persists across sessions | Tool results & lessons are mined and reused |\n\n**Chinese-first**: built for Chinese. Competitors are English-first; AiFP's tokenizer, embeddings (`bge-small-zh`), typo rules, and temporal parser are all Chinese-native.\n\n**Private by default**: SQLite + local embeddings, no cloud, no account, no telemetry. Perception-chain deep tracing is server-enhanced (optional).\n\n**One-command setup**: `npm install -g` auto-configures 10+ AI tools (Claude Code, Cursor, Windsurf, Cline, Gemini CLI, Qwen Code, Zed, VS Code Copilot, Codex CLI, Trae, DeepSeek Harness, pi-coding-agent).\n\n**One brain, many assistants**: all your AI tools share the same local memory. What Claude learns today, Cursor remembers tomorrow — one memory, zero duplication.\n\n## Quick start\n\n```bash\nnpm install -g aifp-mcp\nclaude mcp add ai-cognition -s user -- npx aifp-mcp\n```\n\nRestart Claude Code and you're done. Data lives in `~/.ai-cognition/data/cognition.db`.\n\n### Install from any AI assistant's chat\n\nYou don't need to configure anything manually. In Claude Code, Codex, Cursor, DeepSeek Harness, or any other tool, just ask:\n\n> Install my memory system: `npm install -g aifp-mcp`\n\nThe `postinstall` hook **auto-configures every detected AI tool** (Claude Code, Cursor, Windsurf, Cline, Gemini CLI, Qwen Code, Zed, VS Code Copilot, Codex CLI, Trae, DeepSeek Harness, pi-coding-agent) and prints a status report. Restart the tool and memory tools are available. The agent will see the report and tell you what to restart — no manual MCP configuration needed.\n\n> **First launch**: downloads a ~30 MB embedding model (bge-small-zh), blocking up to 45 s. Later launches are instant (cached).\n\n## Server-enhanced mode\n\nAiFP runs in two modes (env `COGNITION_MODE`, default `remote`):\n\nLocal mode is fully private (data never leaves your machine) but **perception-chain tools require the server**. The server address is not shipped with the package (anti-attack); get it through the official channel.\n\n### One command to connect (after you have a key)\n\n> Access address and key are distributed through the official channel: **contact the author (WeChat: zm8571806 / QQ: 8571806 / email: 8571806@qq.com) to subscribe** — never bundled in this package. Subscriptions can be revoked individually without affecting other users.\n\n```bash\n# 1. Install (if not yet)\nnpm install -g aifp-mcp\n\n# 2. Connect to the server (address + key from the author)\naifp-mcp --connect https://<official-address> <your-64-char-key>\n\n# 3. Restart your AI tool (Claude Code / Cursor / dsh / ...)\n#    Perception chains / deep tracing / graph diffusion become available\n\n# Disconnect (back to pure local):\n# aifp-mcp --disconnect\n```\n\n`--connect` persists the connection in `~/.ai-cognition/server.json` — no need to set env vars every time.\n\n### Even simpler: let your AI configure it\n\nNo need to type commands. In Claude Code / Cursor / Codex / dsh or any AI tool's chat, just say:\n\n> Here are my aifp server address and key, please configure:\n> Address: https://<official-address>\n> Key: <your-64-char-key>\n\nThe AI will run `aifp-mcp --connect` automatically and tell you to restart the tool. Perception-chain enhancement takes effect after restart.\n\n> ⚠️ The key appears in the conversation log. If that bothers you, revoke & reissue it from the admin panel afterward (doesn't affect usage).\n\n### Obsidian integration (notes ↔ memory, both ways)\n\n**Obsidian notes → memory** (AI can semantically search your vault): just ask your AI — **no env vars needed**:\n\n> Import my Obsidian notes into memory: directory = C:/Users/you/Obsidian/MyVault\n\nThe AI calls `reimport_sources` to sync (frontmatter stripped, hash-deduped). Say it again when you add notes.\n\n**Memory → Obsidian notes** (see all memories inside Obsidian): ask your AI to call `export_memories_md`:\n\n> Export memories to Obsidian: directory = C:/Users/you/Obsidian/MyVault/AiFP-memory\n\nExported notes carry frontmatter (type/tier/tags) that Obsidian recognizes; same-name notes are overwritten to stay in sync with the memory base.\n\n\n## MCP tools (33 total)\n\nCore tools (13):\n\n| Tool | Purpose | Chain |\n|------|---------|-------|\n| `save_memory` | Save a memory (auto-dedup + vector index) | Core |\n| `search_memories` | Dual-path retrieval: FTS5 keywords + vector semantics | **Logic** |\n| `recall_context` | One-shot recall (direct hits + causal chains + associations + diffusion) | **Composite** |\n| `get_memory` | Fetch a memory by ID | Core |\n| `list_memories` | Paginated listing | Core |\n| `trace_causal_chain` | BFS causal-chain tracing | **Up/down** |\n| `diffuse_memories` | Multi-hop graph diffusion search | **Relational** |\n| `get_memory_tree` | Hierarchical tree structure | Core |\n| `get_related_memories` | Hebbian co-occurrence associations | **Relational** |\n| `get_user_profile` | User profile — aggregated preferences / facts / habits | **Profile** |\n| `observe_turn` | Queue a conversation turn for auto-recognition (cross-platform memory entry) | **Automatic** |\n| `reimport_sources` | Re-scan external notes directories | Import |\n| `get_stats` | System statistics | Core |\n\nPlus 19 management tools: `get_memory` / `list_memories` / `get_memory_tree` / `get_related_memories` / `consolidate_memories` / `share_memory` / `merge_memories` / `batch_delete` / `batch_update` / `export_memories` / `export_memories_md` (Obsidian) / `explain_query` / `get_confidence_stats` / `scan_memory_patterns` / `validate_memory` / `get_top_experiences` / `deduplicate_memories` / `scan_observation_patterns` / `rotate_observation_logs` / `session_mine`.\n\n## Automatic memory across platforms\n\nClaude Code uses native hooks (100% automatic). Other tools use the `observe_turn` tool + instruction files (see `rules/`):\n\n| Platform | Mechanism | Automation |\n|----------|-----------|------------|\n| **Claude Code** | hooks (native) | 100% automatic |\n| **Cursor** | `.cursor/rules/` instruction file | Triggered when AI follows instructions |\n| **Codex CLI** | `AGENTS.md` instruction file | Triggered when AI follows instructions |\n| **Trae** | project rules (manual) | Triggered when AI follows instructions |\n\nThe instruction files tell the AI: *\"After answering, call `observe_turn` to record this turn.\"* AiFP decides whether anything is worth remembering — no manual decisions needed.\n\n## Core technology\n\n- **SQLite + FTS5** full-text index (CJK-aware, unicode61 tokenizer)\n- **bge-small-zh-v1.5 embeddings** (local 512-dim semantic search, auto-retry + multi-mirror fallback)\n- **Hebbian co-occurrence matrix** (\"neurons that fire together wire together\")\n- **Directional causal chains** (6 relation types)\n- **BFS graph diffusion** (multi-hop discovery of indirect knowledge)\n- **Typo correction + disambiguation + Chinese temporal-phrase parsing**\n\n## How AI tools connect (auto or manual)\n\n**Installed during `npm install -g` (postinstall)** — every detected AI tool gets the MCP config automatically. Later, when you install a NEW AI tool, just run:\n\n```bash\naifp-mcp --setup   # re-detect & configure all AI tools\n```\n\nIt detects installed AI tools (writes only what it finds, never overwrites):\n\n| Platform | Config target |\n|----------|---------------|\n| Claude Code | `~/.claude/settings.json` → mcpServers + startup hook |\n| Cursor | `~/.cursor/mcp.json` |\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` |\n| Cline | `~/.config/cline/mcp_settings.json` |\n| Gemini CLI | `~/.gemini/settings.json` → mcpServers |\n| Qwen Code | `~/.qwen/settings.json` → mcpServers |\n| Zed | `~/.config/zed/settings.json` → context_servers |\n| VS Code Copilot | `%APPDATA%/Code/User/mcp.json` → servers |\n| Codex CLI | `~/.codex/config.toml` |\n| **pi-coding-agent** | extension generated at `~/.pi/agent/extensions/aifp-memory/` |\n\n## Manual configuration\n\n### Claude Code / Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"ai-cognition\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/aifp-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n### Custom data directory\n\n```bash\nCOGNITION_DATA_DIR=/path/to/data npx aifp-mcp\n```\n\n## Environment variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `COGNITION_DATA_DIR` | `~/.ai-cognition/` | Data storage directory |\n| `COGNITION_MODE` | `remote` | `local` local-only / `remote` server-enhanced |\n| `COGNITION_SERVER_URL` | *(none — configure explicitly)* | Remote algorithm-server URL (self-hosted) |\n| `COGNITION_API_KEY` | - | API key for remote mode |\n| `COGNITION_RECOGNIZER` | `0` | Set `1` to enable auto-recognition |\n| `COGNITION_LLM_API_KEY` | - | LLM key for the recognizer (OpenAI-compatible) |\n| `COGNITION_LLM_BASE_URL` | `https://api.deepseek.com` | Recognizer LLM base URL |\n| `COGNITION_LLM_MODEL` | `deepseek-chat` | Recognizer LLM model |\n| `HF_MIRROR` | `https://hf-mirror.com` | Embedding-model download mirror (falls back to huggingface.co) |\n| `CORS_ORIGIN` | `*` | HTTP-mode CORS whitelist |\n| `PORT` | `5000` | HTTP server port |\n\n## Recognizer LLM config (auto memory recognition)\n\nThe observation queue needs an LLM to judge whether a turn is worth remembering. Either:\n\n```bash\n# OpenAI-compatible (DeepSeek recommended)\nexport COGNITION_RECOGNIZER=1\nexport COGNITION_LLM_API_KEY=your-deepseek-key\nexport COGNITION_LLM_BASE_URL=https://api.deepseek.com   # optional\nexport COGNITION_LLM_MODEL=deepseek-chat                 # optional\n\n# or Anthropic\n# export COGNITION_RECOGNIZER=1\n# export ANTHROPIC_API_KEY=sk-ant-...\n```\n\nWithout this, turns are only logged to the observation log and auto-recognition does not persist (explicit `save_memory` calls are unaffected).\n\n## Tech stack\n\n- Node.js 22+ (`node:sqlite`) + TypeScript\n- SQLite (built-in) + FTS5\n- @xenova/transformers (bge-small-zh-v1.5)\n- @modelcontextprotocol/sdk (MCP protocol)\n\n## License\n\nProprietary — see [LICENSE](./LICENSE). Free for personal/non-commercial use; commercial use requires a license. Third-party dependencies keep their own licenses.\n"
}