ZaiMem

Session memory & context enhancer for chat.z.ai — an MCP-powered web service that gives any chat.z.ai agent persistent vector memory, automatic context enhancement, token saving, and smart-skill orchestration — with every user's data mirrored to their own private GitHub repo as a human-readable cloud database.

┌──────────────┐   1. visit    ┌───────────────────┐  2. auto private token
│  ZaiMem web  │ ────────────► │  token issued &   │ ────────────────────────┐
│     app      │               │  stored locally   │                         ▼
└──────────────┘               └───────────────────┘          ┌─────────────────────────────┐
                                                              │ 3. login → get MAGIC PROMPT │
                                                              │ (endpoint + key embedded)   │
                                                              └──────────────┬──────────────┘
                                                                             ▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ 4. paste prompt into a new chat.z.ai AGENT-mode chat                                    │
│    → session auto-synced: vector memory, context enhancement, token saving, skills      │
└─────────────────────────────────────────────────────────────────────────────────────────┘
                                                                             │
                                     ┌───────────────────────────────────────┘
                                     ▼
              5. pair GitHub PAT → private repo auto-created
                 → ALL data auto-synced (repo = user's cloud DB)

Features

• Automated private tokens — no signup: visit the app, get a zm_… token instantly, log in with it.

• Magic prompt — the dashboard generates a ready-to-paste activation prompt with your MCP endpoint and key embedded. Paste it into any chat.z.ai agent-mode chat and the session is wired to ZaiMem.

• MCP server (JSON-RPC 2.0, streamable HTTP) — 12 tools, 3 resources, prompt templates, batch calls, session ids, CORS.

• Local vector memory — 384-dim hashed word/bigram/char-4gram embeddings with cosine recall; auto-dedupe (0.94 duplicate / 0.80 merge thresholds), recency + keyword boosts, context-block assembly.

• Token saver — LLM-powered digests (with extractive fallback) compress long context; token accounting per action.

• Smart skills (zcode-smart-skill integration) — SKILL.md skill registry, auto trigger detection, difficulty budgets (E5: 2/6/12), ledger pages (notes.md, tasks.json) with size budgets, handoff brief with TRUST clause, reflection schema.

• GitHub Cloud DB — pair a GitHub PAT; a private repo is auto-created and every data change is auto-synced (sha-based idempotent pushes, 4s debounced, full audit trail). Your repo, your data.

• Scheduled daily backup — an optional heartbeat push of a full snapshot ~every 24h (configurable via ZAIMEM_BACKUP_HOURS), even when nothing changed — proof the backup pipeline is alive. Toggle it in the Cloud DB panel.

• Global search (⌘K) — one query across all sessions, memories (vector + substring), ledger pages and skills, with jump-to-result navigation. Filter results by kind (sessions / memories / ledger / skills) and by date range (24 h → 1 year) right from the command bar.

Related MCP server: memorix

Quick start

Clone & run locally

# 1. clone the repo
git clone https://github.com/romangalaxys10-spec/zaimem.git
cd zaimem

# 2. install dependencies (bun ≥ 1.2 recommended; npm/pnpm work too)
bun install

# 3. configure env
cp .env.example .env        # SQLite by default

# 4. create the database schema
bun run db:push

# 5. run
bun run dev                 # http://localhost:3000

Production build: bun run build → bun run start (standalone output on localhost:3000).

Deploy with Docker (public demo / self-host)

Every push to main publishes a fresh image to GHCR via Actions (docker.yml):

# pull the prebuilt image and run — http://localhost:3000
docker pull ghcr.io/romangalaxys10-spec/zaimem:latest
docker run -d -p 3000:3000 -v zaimem-db:/app/db ghcr.io/romangalaxys10-spec/zaimem:latest

# or build & run from source in one command
docker compose up --build -d

# or without compose
docker build -t zaimem .
docker run -d -p 3000:3000 -v zaimem-db:/app/db zaimem

Image tags: latest (default branch), vX.Y.Z / vX.Y (git tags), short sha-*, and the branch name. Browse all tags on the package page.

The SQLite database lives in the zaimem-db volume (mounted at /app/db) and survives rebuilds. Healthcheck, restart policy and env knobs are pre-configured in docker-compose.yml.

Expose port 3000 through your reverse proxy / tunnel (Caddy, nginx, Cloudflare Tunnel) for a public demo — all agent traffic goes through the single MCP endpoint /api/mcp.

First run

Then open the app → Get my private token → log in → copy the Magic Prompt → paste into a new chat.z.ai agent-mode chat.

MCP endpoint

POST /api/mcp
Authorization: Bearer <api-key>        # or ?token=<api-key>
Content-Type: application/json

The endpoint implements the Model Context Protocol over streamable HTTP (initialize, tools/list, tools/call, resources/*, prompts/*, batch arrays, MCP-Session-Id).

Tools

Resources & prompts

• zaimem://protocol — operating protocol (markdown)

• zaimem://memory — recent memories (json)

• zaimem://skills — skill registry (json)

• Prompt template zaimem-boot — boot a ZaiMem-synced session with memory recall

Dashboard REST API

GitHub Cloud DB

Pair your PAT (classic, repo scope) from the dashboard's Cloud DB tab:

1. PAT is validated against GET /user and stored AES-256-GCM encrypted (only last 4 chars are ever displayed).

2. A private repo (default zaimem-cloud-db) is auto-created in your account.

3. Every mutation (memories, sessions, ledger, skills, stats) triggers a debounced auto-sync.

4. Pushes are idempotent — unchanged files are skipped via git blob SHA comparison; your own files in the repo are never touched.

Repo layout:

index.json            # snapshot index + counts
README.md             # human-readable overview (regenerated)
memories.json         # all memories
vectors.jsonl         # 384-dim embeddings, one JSON per line
sessions/<slug>.json  # one file per session (turns, summary, metadata)
skills.json           # skill registry
stats.json            # usage statistics
sync/log.json         # sync audit trail

Architecture

src/
├── app/api/…            # 12 route handlers (auth, sessions, memories, skills, stats, github, mcp)
├── components/zaimem/…  # landing, dashboard, cloud-db, panels, magic-prompt builder
└── lib/zaimem/
    ├── vector.ts        # hashed n-gram embeddings + cosine engine
    ├── memory.ts        # remember/recall/enhance with dedupe & boosts
    ├── compress.ts      # token saver (LLM digest + extractive fallback)
    ├── skills.ts        # smart-skill engine (triggers, budgets, ledger, handoff)
    ├── mcp.ts           # MCP tool/resource/prompt registry & dispatcher
    ├── github.ts        # PAT validation, repo provisioning, idempotent sync, debounce queue
    ├── crypto.ts        # AES-256-GCM at-rest encryption, blob sha
    ├── auth.ts          # token issuance & session auth
    └── seed.ts          # builtin skills bootstrap

Stack: Next.js 16 (App Router) · React 19 · TypeScript · Tailwind CSS 4 · shadcn/ui · Prisma + SQLite · z-ai-web-dev-sdk.

Testing

bun scripts/e2e-test.ts          # 46 HTTP checks — auth, MCP tools, dedupe, GitHub guards …
bun scripts/e2e-github-unit.ts   # 26 engine checks — full sync engine vs mock GitHub API

Security notes

• Login tokens and API keys are high-entropy random strings; API keys authenticate every MCP call.

• GitHub PATs are encrypted at rest (AES-256-GCM, scrypt-derived key) and never returned by the API.

• The SQLite database and .env are local-only and excluded from version control.

Community & links

License

MIT © RyzenCode