docs: add VitePress documentation site by igorls · Pull Request #439 · MemPalace/mempalace

igorls · 2026-04-09T21:55:52Z

Summary

Comprehensive VitePress documentation site for MemPalace with 22 content pages across 3 sections.

Live preview: https://mempalace-docs.netlify.app/

What's Included

Site Structure

Guide (9 pages): Getting Started, Mining, Searching, MCP Integration, Claude Code, Gemini CLI, Local Models, Auto-Save Hooks, Configuration
Concepts (6 pages): The Palace, Memory Stack, AAAK Dialect, Knowledge Graph, Specialist Agents, Contradiction Detection
Reference (7 pages): CLI Commands, MCP Tools (all 19 schemas), Python API, API Reference, Module Map, Benchmarks, Contributing

Theme & Design

Custom indigo/cyan palette with dark mode default
Lucide icons on feature cards
Mermaid diagrams for architecture visualization
Inter + JetBrains Mono typography
Animated hero gradient, hover effects on feature cards

Landing Page

Hero with benchmark tagline (96.6% LongMemEval recall)
6 feature cards with Lucide icons
Benchmark comparison table vs Mem0, Mastra, etc.

Infrastructure

GitHub Actions workflow for GitHub Pages deployment (deploy-docs.yml)
Local search enabled via VitePress built-in
Edit links pointing to this repo

Content Sources

All content derived from actual source code and existing documentation — no fabricated information:

README.md → Guide and Concepts sections
benchmarks/BENCHMARKS.md → curated summary in Reference
hooks/README.md → Auto-Save Hooks guide
Source modules (searcher.py, layers.py, knowledge_graph.py, palace_graph.py, dialect.py, mcp_server.py, cli.py) → API Reference pages

Build

cd website
bun install
bun run docs:build   # ~6s, zero errors
bun run docs:dev     # local dev server

Copilot

Pull request overview

This PR introduces a VitePress-based documentation site for MemPalace, along with supporting infrastructure for publishing and a new benchmark test suite.

Changes:

Add a full VitePress documentation site under website/ (Guide / Concepts / Reference pages, theme styling, icons, and build config).
Add GitHub Pages + Netlify build/deploy configuration for the docs site.
Add a substantial tests/benchmarks/ suite plus CI workflow updates, and bump the package/plugin version to 3.0.14.

Reviewed changes

Copilot reviewed 47 out of 56 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`.github/workflows/deploy-docs.yml`	Builds and deploys `website/` to GitHub Pages.
`.github/workflows/ci.yml`	Adjusts CI to ignore benchmarks in unit tests and adds a dedicated benchmark job.
`website/.vitepress/config.mts`	VitePress site config (nav/sidebar/search/base/head/edit links).
`website/.vitepress/theme/index.ts`	Theme entrypoint loading custom CSS.
`website/.vitepress/theme/style.css`	Custom theme palette, typography, and component styling.
`website/index.md`	Landing page content + feature cards + benchmark table.
`website/guide/*.md`	User guide pages for install, mining, searching, MCP integration, hooks, etc.
`website/concepts/*.md`	Concept pages (palace structure, stack, AAAK, KG, agents, contradiction detection).
`website/reference/*.md`	Reference docs for CLI, MCP tool schemas, Python API, module map, benchmarks, contributing.
`website/public/icons/*.svg`	Lucide-derived SVG icons used on the landing page feature cards.
`website/package.json`	Docs site dev/build scripts + VitePress/Mermaid dependencies.
`website/.gitignore`	Ignore rules for docs site build artifacts and dependencies.
`netlify.toml`	Netlify build configuration for the docs site.
`tests/benchmarks/*`	New benchmark framework (data generation, metrics reporting, performance tests).
`pyproject.toml`	Version bump + dev deps (psutil) + pytest markers/pythonpath.
`mempalace/version.py`	Version bump to `3.0.14`.
`.claude-plugin/`, `.codex-plugin/`	Plugin metadata version bump to `3.0.14`.
`docs/review.md`, `docs/ISSUES.md`	Adds audit/review material and an issue tracker snapshot.
`benchmarks/run_with_ollama.py`	Adds an Ollama embedding runner for LongMemEval benchmarking.
`.gitignore`	Ignore `.claude/` and benchmark results JSONL files.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-09T22:02:18Z

+dialect = Dialect()
+compressed = dialect.compress("We decided to use GraphQL...")
+
+# With entity mappings
+dialect = Dialect(entities={"Alice": "ALC", "Bob": "BOB"})
+compressed = dialect.compress(text, metadata={"wing": "myapp"})
+
+# From config
+dialect = Dialect.from_config("entities.json")
+
+# Stats
+stats = dialect.compression_stats(original, compressed)
+```


In the AAAK Dialect example, text, original, and compressed are used without being defined (dialect.compress(text, ...) and compression_stats(original, compressed)). This makes the snippet non-runnable and confusing. Suggest defining these variables in the example (or reusing the earlier literal string) so the copy/paste path works.

Copilot

Pull request overview

Copilot reviewed 29 out of 37 changed files in this pull request and generated 9 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-09T22:18:59Z

+├── tests/                     ← test suite
+├── assets/                    ← logo + brand
+└── pyproject.toml             ← package config (v3.0.14)
+```


The module tree says pyproject.toml is v3.0.14, but the repo's pyproject.toml currently has version 3.1.0. Please update this to avoid drifting version references in the docs.

Copilot · 2026-04-09T22:19:00Z

+from mempalace.searcher import search_memories
+
+results = search_memories(
+    query="why did we switch to GraphQL",
+    palace_path="~/.mempalace/palace",
+    wing="myapp",          # optional filter
+    room="architecture",   # optional filter
+    n_results=5,
+)


These Python examples pass paths containing ~ (e.g. palace_path="~/.mempalace/palace"). The library functions (e.g. search_memories) do not expand ~, so this literal string can fail unless callers expand it themselves. Prefer MempalaceConfig().palace_path or os.path.expanduser(...) in the docs.

Copilot · 2026-04-09T22:19:00Z

+from mempalace.layers import MemoryStack
+
+stack = MemoryStack(
+    palace_path="~/.mempalace/palace",   # optional
+    identity_path="~/.mempalace/identity.txt",  # optional
+)
+


Same issue here: MemoryStack(palace_path="~/.mempalace/palace", identity_path="~/.mempalace/identity.txt") will not expand ~ internally. Consider either omitting these args (letting defaults handle expansion) or showing os.path.expanduser / MempalaceConfig usage.

Copilot · 2026-04-09T22:19:00Z

+from mempalace.knowledge_graph import KnowledgeGraph
+
+kg = KnowledgeGraph(db_path="~/.mempalace/knowledge_graph.sqlite3")
+


KnowledgeGraph(db_path="~/.mempalace/knowledge_graph.sqlite3") passes an unexpanded ~ path; KnowledgeGraph does not expanduser on provided db_path. Either omit db_path (use default) or show os.path.expanduser(...) to prevent creating ./~/... relative paths.

Copilot · 2026-04-09T22:19:00Z

+### `mempalace_add_drawer`
+
+File verbatim content into the palace. Checks for duplicates first.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `wing` | string | **Yes** | Wing (project name) |
+| `room` | string | **Yes** | Room (aspect: backend, decisions, etc.) |
+| `content` | string | **Yes** | Verbatim content to store |
+| `source_file` | string | No | Where this came from |
+| `added_by` | string | No | Who is filing (default: "mcp") |
+
+**Returns:** `{ success, drawer_id, wing, room }` or `{ success: false, reason: "duplicate" }`
+


The docs say mempalace_add_drawer “checks for duplicates first” and may return { success: false, reason: "duplicate" }, but the current MCP implementation doesn’t run a similarity duplicate check before filing and doesn’t return this shape (it only no-ops on an identical deterministic drawer_id). Please align the tool description/return values with the actual behavior and point users to mempalace_check_duplicate if they want similarity-based checks.

- 22 content pages across Guide, Concepts, and Reference sections - Custom indigo/cyan theme with Lucide icons and Mermaid diagrams - GitHub Actions workflow for GitHub Pages deployment - Live preview: https://mempalace-docs.netlify.app/

Copilot

Pull request overview

Copilot reviewed 29 out of 37 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-09T22:50:56Z

+```json
+{
+  "palace_path": "/custom/path/to/palace",
+  "collection_name": "mempalace_drawers",
+  "people_map": {"Kai": "KAI", "Priya": "PRI"}
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `palace_path` | `~/.mempalace/palace` | Where ChromaDB stores your drawers |
+| `collection_name` | `mempalace_drawers` | ChromaDB collection name |
+| `people_map` | `{}` | Entity name → AAAK code mappings |
+


people_map is documented here as “Entity name → AAAK code mappings”, but in MempalaceConfig it’s described as a mapping of name variants to canonical names and it isn’t used for Dialect entity codes (those are read from entities.json via Dialect.from_config). This section should either correct the meaning of people_map or remove it from the global config example/table to avoid sending users to the wrong knob for AAAK.

Copilot · 2026-04-09T22:50:56Z

+export default withMermaid(
+  defineConfig({
+    title: 'MemPalace',
+    description: 'Give your AI a memory. Local-first storage and retrieval for AI workflows, with benchmark results and MCP tooling.',
+    base: docsBase,
+
+    head: [


PR description mentions “dark mode default”, but the VitePress config doesn’t set appearance/initial theme, so the site will follow system preference by default. Either adjust the description or set the VitePress appearance option to default to dark so the implementation matches the stated behavior.

Copilot · 2026-04-09T22:50:57Z

+stack = MemoryStack()  # uses default paths from MempalaceConfig
+
+# Wake-up: L0 (identity) + L1 (essential story)
+context = stack.wake_up(wing="myapp")  # ~170-900 tokens
+


The wake-up token estimate here (~170–900) is inconsistent with the implementation and the rest of the docs: MemoryStack.wake_up() always includes L0 + L1 and is typically ~600–900 tokens per mempalace/layers.py. Consider aligning this range (or explaining under what conditions it could be as low as ~170) to avoid confusing users about expected prompt budget.

Copilot · 2026-04-09T22:50:57Z

+# CLI Commands
+
+All commands accept `--palace <path>` to override the default palace location.
+
+## `mempalace init`
+


The CLI includes a mempalace mcp command (prints MCP setup instructions), but it isn’t documented on this page. Since this is the CLI reference, consider adding a short mempalace mcp section so users can discover it alongside the other subcommands.

web3guru888

Impressive effort — 22 content pages across guide, concepts, and reference sections, all sourced from actual code and docs. The live preview on Netlify looks polished.

A few observations:

This will conflict with #470 (GitHub Pages landing workflow) since both deploy to Pages. Might want to coordinate.
Including bun.lock (633 lines) in the PR — most projects .gitignore lockfiles for docs sites, or at least the maintainers may prefer npm for consistency with the Python toolchain.
The MCP tools reference with all 19 schemas is genuinely useful — that's the kind of thing that's hard to find by reading source.

Nice contribution for the project's discoverability.

🔭 Reviewed as part of the MemPalace-AGI integration project — autonomous research with perfect memory. Community interaction updates are posted regularly on the dashboard.

- Update totals to 155 open issues / 192 open PRs (+63/+60 in one day) - Add unlabeled-bugs section for upstream label debt - Track new critical findings: MemPalace#538, MemPalace#525, MemPalace#521, MemPalace#469, MemPalace#479, MemPalace#477, MemPalace#475 - Add PR MemPalace#439 (VitePress docs site) to audit PR table - Mark closed items: MemPalace#394, MemPalace#296, MemPalace#290, MemPalace#214, MemPalace#186, MemPalace#180, MemPalace#179, MemPalace#163 et al.

Co-authored-by: Copilot <[email protected]>

Copilot AI review requested due to automatic review settings April 9, 2026 21:55

Copilot started reviewing on behalf of igorls April 9, 2026 21:56 View session

igorls force-pushed the docs/vitepress-site branch from 72fb625 to 27aedba Compare April 9, 2026 21:58

Copilot AI reviewed Apr 9, 2026

View reviewed changes

igorls force-pushed the docs/vitepress-site branch from 27aedba to ae0f592 Compare April 9, 2026 22:11

igorls requested a review from Copilot April 9, 2026 22:12

Copilot started reviewing on behalf of igorls April 9, 2026 22:12 View session

igorls force-pushed the docs/vitepress-site branch from ae0f592 to c14e535 Compare April 9, 2026 22:16

Copilot AI reviewed Apr 9, 2026

View reviewed changes

igorls force-pushed the docs/vitepress-site branch from c14e535 to dfb22f5 Compare April 9, 2026 22:41

igorls requested a review from Copilot April 9, 2026 22:44

Copilot started reviewing on behalf of igorls April 9, 2026 22:44 View session

Copilot AI reviewed Apr 9, 2026

View reviewed changes

web3guru888 mentioned this pull request Apr 10, 2026

ci: add GitHub Pages landing workflow #470

Open

web3guru888 reviewed Apr 10, 2026

View reviewed changes

bensig self-requested a review April 10, 2026 06:45

bensig previously approved these changes Apr 10, 2026

View reviewed changes

igorls dismissed bensig’s stale review via f26f87d April 10, 2026 14:44

igorls force-pushed the docs/vitepress-site branch 2 times, most recently from f26f87d to b3b6910 Compare April 10, 2026 14:46

Merge branch 'main' into docs/vitepress-site

6d70dfd

igorls force-pushed the docs/vitepress-site branch from b3b6910 to 6d70dfd Compare April 10, 2026 14:49

feat: Netlify configuration

697f651

Merge branch 'main' into docs/vitepress-site

5b77083

igorls requested a review from milla-jovovich as a code owner April 10, 2026 16:22

igorls added 2 commits April 10, 2026 13:48

Merge branch 'main' into docs/vitepress-site

8a0488f

Merge branch 'main' into docs/vitepress-site

410d224

bensig self-requested a review April 11, 2026 05:21

Apply suggestion from @Copilot

6117606

Co-authored-by: Copilot <[email protected]>

bensig approved these changes Apr 11, 2026

View reviewed changes

bensig changed the base branch from main to develop April 11, 2026 22:22

igorls merged commit f224c48 into MemPalace:develop Apr 12, 2026
6 checks passed

igorls deleted the docs/vitepress-site branch April 12, 2026 07:56

This was referenced Apr 13, 2026

chore: sync main into develop after v3.2.0 release #766

Closed

docs: fix stale org URLs in website and plugin manifests (#787) #808

Merged

		from mempalace.knowledge_graph import KnowledgeGraph

		kg = KnowledgeGraph(db_path="~/.mempalace/knowledge_graph.sqlite3")

Conversation

igorls commented Apr 9, 2026

Summary

What's Included

Site Structure

Theme & Design

Landing Page

Infrastructure

Content Sources

Build

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

web3guru888 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants