me.ai-know/memory
Chinese-first brain-inspired memory MCP — hybrid recall, 7-layer user profile, workspace assembly.
Open source Repository Open in the app JSON README (API)
About
Chinese-first brain-inspired memory MCP — hybrid recall, 7-layer user profile, workspace assembly.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- me.ai-know
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.4.0
- Last push
- 2026-08-20T03:25:51Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 04:01:49
- Updated
- 2026-08-29 04:01:49
- Origin id
me.ai-know/memory
README
# 知己 (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`](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
```
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:
```bash
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):
```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:
```bash
npm install # only @modelcontextprotocol/sdk + zod
```
Then in your client 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`](MCP-USAGE.md).
## Architecture — a stateless thin bridge
```
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`](MCP-USAGE.md) — full guide (install, all clients, per-tool reference, troubleshooting, FAQ)
- Online: <https://ai-know.me/mcp>
## License
[MIT](LICENSE) © 2026 知己 AI (ai-know.me)
---
*知己 AI · MCP integration — Chinese-first brain-inspired memory. The bridge is open; the memory intelligence lives in the Zhiji backend.*