# memory [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/xfhxxffhh224/zhiji-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 497  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/memory-9

## Description
Chinese-first brain-inspired memory MCP — hybrid recall, 7-layer user profile, workspace assembly.

## Tools
Capabilities this server exposes over MCP:

- **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.
- **zhiji_memory_search** — Lighter, recall-only: the 11-stage hybrid pipeline (trigram FTS + semantic + time-decay), returns scored snippets with sources.
- **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.
- **zhiji_memory_ingest** — Write a conversation turn to long-term memory; async embedding + profile/fact extraction + importance scoring follow. **Text only.
- **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.
- **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.
- **zhiji_status** — Health & memory scale (files / chunks / FTS availability). Call first to verify connectivity.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "memory": {
    "command": "npx",
    "args": ["-y","@modelcontextprotocol/inspector"]
  }
}
```

## Documentation & 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`](https://github.com/xfhxxffhh224/zhiji-mcp/blob/HEAD/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`](https://github.com/xfhxxffhh224/zhiji-mcp/blob/HEAD/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`](https://github.com/xfhxxffhh224/zhiji-mcp/blob/HEAD/MCP-USAGE.md) — full guide (install, all clients, per-tool reference, troubleshooting, FAQ)
- Online: <https://ai-know.me/mcp>

## License

[MIT](https://github.com/xfhxxffhh224/zhiji-mcp/blob/HEAD/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.*