知己 (Zhiji) Memory — MCP Server

Chinese-first, brain-inspired long-term memory as an MCP server. Give any MCP client — Claude Desktop / Claude Code / Cursor / Cline / Cherry Studio / Coze — the ability to remember and understand your user across sessions.

中文用户：完整接入手册见 MCP-USAGE.md,或在线版 https://ai-know.me/mcp。

v0.4.0 · 9 tools / 2 resources / 1 prompt · stdio + Streamable HTTP · MCP protocol 2025-11-25

This repo is a thin bridge: it translates MCP tool calls into REST calls to the Zhiji backend (hosted at ai-know.me). The bridge stores nothing; all memory lives in the Zhiji service you connect to.

Why not just another vector-memory MCP?

Mem0 / Zep / LangMem expose add / search / delete over a vector store. 知己 exposes brain-inspired primitives:

11-stage hybrid retrieval — trigram full-text + bge-large-zh semantic + time-decay + access-reinforcement + dedup ranking.
7-layer / 37-dimension evolving user profile — values, decision logic, behavior style, self-cognition, interoceptive & dynamic state.
Workspace assembly — one call returns profile + relevant memories + confirmed facts + behavioral inferences, budget-trimmed for the client context window.
Prospective reminders, multimodal ingest (audio / OCR / doc), and a self-evolving reward loop driven by user feedback.

All Chinese-optimized (trigram tokenizer + bge-large-zh); English is supported too. Memory is stored in the Zhiji backend you connect to — self-host it, or use the hosted ai-know.me service; either way it's your Zhiji instance, not a generic memory-SaaS middleman.

Tools, resources & prompts

9 tools, grouped by role. Every user-scoped tool takes userEmail (or falls back to MB_USER_EMAIL); only the notable extra params are listed.

Read — understand the user

Tool	What it does	Notable params
`zhiji_workspace_assemble`	Flagship. One call returns everything needed to understand this user for a query — relevant memories + profile + confirmed facts + behavioral inferences (plus counterfactual & cross-domain hints). Drop straight into any LLM's context.	`query`; `maxResults` ≤20 (def 6). Slow "what-if" queries can take 10–15s.
`zhiji_memory_search`	Lighter, recall-only: the 11-stage hybrid pipeline (trigram FTS + semantic + time-decay), returns scored snippets with sources.	`query`; `maxResults` ≤50 (def 8)
`zhiji_profile_get`	7-layer / 37-dim user profile as an inject-ready natural-language summary.	—
`zhiji_facts_get`	Structured atomic facts (subject attribution, confidence, conflict status) — for exact names/dates/counts, not narrative.	—
`zhiji_prospective_due`	Due/upcoming intentions (todos, promises, plans) within a time window — for proactively nudging the user.	`hours` ≤720 (def 24)

Write — feed memory

Tool	What it does	Notable params
`zhiji_memory_ingest`	Write a conversation turn to long-term memory; async embedding + profile/fact extraction + importance scoring follow. Text only.	`conversationId`; `messages[{ author: "user"\|"bot", text }]`
`zhiji_ingest_file`	Multimodal ingest — audio / image / PDF / Word / Excel / video → Whisper transcribe / Tesseract OCR / doc parse → memory. Audio & video also get acoustic-emotion analysis.	one of `path` \| `url` \| `base64`; `filename`; `isUserVoice`

Ops — improve & diagnose

Tool	What it does	Notable params
`zhiji_feedback`	Thumbs up/down on the last recall/answer → feeds the self-evolution reward and reinforces (or penalizes) the Q-value of recently retrieved memories. The "gets better the more you use it" loop.	`rating: "up"\|"down"`; `weak?` → ±0.5
`zhiji_status`	Health & memory scale (files / chunks / FTS availability). Call first to verify connectivity.	—

2 resources — zhiji://schema/dimensions (authoritative 7-layer / 37-dim profile schema) · zhiji://server/status (live service status). 1 prompt — personal-context: weaves profile + memories + facts into a ready-to-prepend system prompt for a given query.

Experimental capabilities (sleep consolidation / dream replay / emergence) are not exposed until their groundedness passes ablation.

Typical flow

Code

zhiji_status              → verify connectivity
zhiji_memory_ingest       → feed a conversation  (or zhiji_ingest_file for audio/docs)
zhiji_workspace_assemble  → in a *new* session, recall + understand the user
zhiji_feedback            → thumbs up/down, closing the self-evolution loop

Quick start

You need an agent Key (mb- prefix). Get one at https://ai-know.me/memory?tab=api (register + create a Key bound to your account).

Option A — remote, no install (recommended)

Point any Streamable-HTTP MCP client at the hosted endpoint — you don't need this repo at all:

Terminal

claude mcp add zhiji-memory --transport http \
  --url https://ai-know.me/mcp \
  --header "Authorization: Bearer mb-yourKey"

Or in a URL-style client config (Cursor / Cherry Studio / LobeChat):

config.json

{
  "mcpServers": {
    "zhiji-memory": {
      "url": "https://ai-know.me/mcp",
      "headers": { "Authorization": "Bearer mb-yourKey" }
    }
  }
}

Option B — run this bridge locally (stdio)

Use this repo when you want the bridge as a local stdio process (e.g. a desktop client launches it for you), talking to the hosted Zhiji backend:

Terminal

npm install   # only @modelcontextprotocol/sdk + zod

Then in your client config:

config.json

{
  "mcpServers": {
    "zhiji-memory": {
      "command": "node",
      "args": ["/absolute/path/to/zhiji-mcp/zhiji-mcp-server.mjs"],
      "env": {
        "MB_BASE_URL": "https://ai-know.me",
        "MB_API_KEY": "mb-yourKey"
      }
    }
  }
}

Verify

bash

# visual debugger — should list 9 tools / 2 resources / 1 prompt
npx @modelcontextprotocol/inspector node zhiji-mcp-server.mjs

Full client matrix (LangChain, OpenAI Agents SDK, Coze…) is in MCP-USAGE.md.

Architecture — a stateless thin bridge

Code

MCP client  ──stdio / HTTP(JSON-RPC)──►  zhiji-mcp-*.mjs  ──REST──►  Zhiji backend (ai-know.me)

The MCP layer stores nothing; it translates MCP tool calls into REST calls to the Zhiji backend. Shared core zhiji-mcp-core.mjs backs both entry points:

File	Role
`zhiji-mcp-core.mjs`	Tool/resource/prompt definitions (single source of truth)
`zhiji-mcp-server.mjs`	stdio entry (`npm start`)
`zhiji-mcp-http.mjs`	Streamable HTTP entry (`npm run http`)

Isolation & auth

All data is hard-isolated by userEmail. The bridge treats userEmail as a namespace, not a credential.
The hosted public endpoint requires an agent Key — requests without Bearer mb-… get 401; the backend binds each Key to its userEmail and rejects cross-user access.
Never hand a key-less, userEmail-swappable bridge to end users — front it with your own backend that injects the correct userEmail. See MCP-USAGE.md §8.

Environment

Var	Default	Notes
`MB_BASE_URL`	`http://localhost:3001`	Zhiji backend address; for the hosted service use `https://ai-know.me`
`MB_USER_EMAIL`	—	default user namespace (single-user local use)
`MB_API_KEY`	—	`mb-` agent Key; forwarded as Bearer
`MB_TIMEOUT_MS`	`60000`	slow workspace routes can take ~15s

Status

Version	Highlights
v0.4	`zhiji_ingest_file` (9 tools) + public-release hardening (TLS, `MCP_REQUIRE_KEY`, JWT-only key issuance, cross-user isolation hard-test)
v0.5 (planned)	inference-list tool, resource subscriptions, fine-grained key permissions

Docs

MCP-USAGE.md — full guide (install, all clients, per-tool reference, troubleshooting, FAQ)
Online: https://ai-know.me/mcp

License

知己 AI · MCP integration — Chinese-first brain-inspired memory. The bridge is open; the memory intelligence lives in the Zhiji backend.