gitmem-dev · CLCrawford-dev · Feb 18, 2026 · Feb 18, 2026
diff --git a/apps/docs/.gitignore b/apps/docs/.gitignore
@@ -0,0 +1,4 @@
+node_modules/
+.next/
+.source/
+out/
diff --git a/apps/docs/app/docs/[[...slug]]/page.tsx b/apps/docs/app/docs/[[...slug]]/page.tsx
@@ -0,0 +1,47 @@
+import { source } from "@/lib/source";
+import {
+  DocsPage,
+  DocsBody,
+  DocsTitle,
+  DocsDescription,
+} from "fumadocs-ui/page";
+import { notFound } from "next/navigation";
+import defaultMdxComponents from "fumadocs-ui/mdx";
+import type { Metadata } from "next";
+
+interface PageProps {
+  params: Promise<{ slug?: string[] }>;
+}
+
+export default async function Page(props: PageProps) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  const MDX = page.data.body;
+
+  return (
+    <DocsPage toc={page.data.toc}>
+      <DocsTitle>{page.data.title}</DocsTitle>
+      <DocsDescription>{page.data.description}</DocsDescription>
+      <DocsBody>
+        <MDX components={{ ...defaultMdxComponents }} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export async function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata(props: PageProps): Promise<Metadata> {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+  };
+}
diff --git a/apps/docs/app/docs/layout.tsx b/apps/docs/app/docs/layout.tsx
@@ -0,0 +1,19 @@
+import { DocsLayout } from "fumadocs-ui/layouts/docs";
+import { baseOptions } from "@/lib/layout.shared";
+import { source } from "@/lib/source";
+import type { ReactNode } from "react";
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <DocsLayout
+      {...baseOptions()}
+      tree={source.getPageTree()}
+      sidebar={{
+        defaultOpenLevel: 1,
+        collapsible: true,
+      }}
+    >
+      {children}
+    </DocsLayout>
+  );
+}
diff --git a/apps/docs/app/global.css b/apps/docs/app/global.css
@@ -0,0 +1,3 @@
+@import "tailwindcss";
+@import "fumadocs-ui/css/neutral.css";
+@import "fumadocs-ui/css/preset.css";
diff --git a/apps/docs/app/layout.tsx b/apps/docs/app/layout.tsx
@@ -0,0 +1,22 @@
+import { RootProvider } from "fumadocs-ui/provider/next";
+import type { ReactNode } from "react";
+import type { Metadata } from "next";
+import "./global.css";
+
+export const metadata: Metadata = {
+  title: {
+    template: "%s | GitMem",
+    default: "GitMem Documentation",
+  },
+  description: "Institutional memory for AI coding agents. Never repeat the same mistake.",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <RootProvider>{children}</RootProvider>
+      </body>
+    </html>
+  );
+}
diff --git a/apps/docs/app/page.tsx b/apps/docs/app/page.tsx
@@ -0,0 +1,3 @@
+export default function HomePage() {
+  return null;
+}
diff --git a/apps/docs/content/docs/changelog.mdx b/apps/docs/content/docs/changelog.mdx
@@ -0,0 +1,50 @@
+---
+title: Changelog
+description: GitMem release history.
+---
+
+# Changelog
+
+## v1.0.2 (2026-02-15)
+
+### Features
+
+- **`npx gitmem init`** — Interactive setup wizard that detects existing config, prompts, and merges without destroying anything. Replaces the multi-step manual setup.
+  - 6 steps: memory store, MCP server, CLAUDE.md, permissions, hooks, gitignore
+  - Flags: `--yes` (non-interactive), `--dry-run` (preview), `--project <name>`
+  - Idempotent — re-running safely skips completed steps
+- **`npx gitmem uninstall`** — Clean reversal of everything init did. Memory data (`.gitmem/`) preserved by default, `--all` to also delete.
+
+### Docs
+
+- Updated README to feature one-command setup, added gitmem.ai link
+- Updated docs site installation and getting-started pages
+
+## v1.0.1 (2026-02-14)
+
+### Bug Fixes
+
+- Fixed stdout corruption — 22 `console.log` calls replaced with `console.error` in check.ts
+- Error messages now surface in `create_learning` and `record_scar_usage` responses via `errors[]` array
+- Session ID validation added to `session_close` — returns clear error with UUID format example instead of confusing DB lookup failure
+- Removed hardcoded project enum — project names are now free-form strings
+
+### Tests
+
+- +2 regression tests for stdout purity
+- +8 tests for error message surfacing
+- +10 tests for session ID validation
+
+## v1.0.0 (2026-02-15)
+
+### Initial Release
+
+- 23 core tools (free tier) / 29 tools (pro tier)
+- Session management with closing ceremony
+- Scar recall with semantic search
+- Thread tracking across sessions
+- Multi-agent context injection
+- Knowledge graph traversal
+- Local `.gitmem/` storage (free) or Supabase (pro)
+- Claude Code hooks for automatic session management
+- 660+ automated tests across 6 tiers
diff --git a/apps/docs/content/docs/concepts/index.mdx b/apps/docs/content/docs/concepts/index.mdx
@@ -0,0 +1,27 @@
+---
+title: Core Concepts
+description: Understand the building blocks of GitMem's institutional memory system.
+---
+
+# Core Concepts
+
+GitMem is built around a few key ideas that work together to give AI agents persistent, actionable memory.
+
+## The Memory Loop
+
+```
+recall → work → learn → close → recall → ...
+```
+
+1. **Recall** — Before acting, check what you've learned before
+2. **Work** — Do the task, applying past lessons
+3. **Learn** — Capture new scars, wins, and patterns
+4. **Close** — Persist session context for next time
+
+## Key Concepts
+
+- [Scars](/docs/concepts/scars) — Mistakes captured as institutional memory, surfaced before you repeat them
+- [Sessions](/docs/concepts/sessions) — Bounded work periods with context loading and closing ceremonies
+- [Threads](/docs/concepts/threads) — Unresolved work that carries across sessions
+- [Learning Types](/docs/concepts/learning-types) — Scars, wins, patterns, and anti-patterns
+- [Tiers](/docs/concepts/tiers) — Free (local) vs Pro (Supabase) capabilities
diff --git a/apps/docs/content/docs/concepts/learning-types.mdx b/apps/docs/content/docs/concepts/learning-types.mdx
@@ -0,0 +1,79 @@
+---
+title: Learning Types
+description: The four types of institutional memory in GitMem.
+---
+
+# Learning Types
+
+GitMem supports four types of institutional memory, each serving a different purpose.
+
+## Scars
+
+**Mistakes to avoid.** The most common learning type. Scars are surfaced automatically via `recall` when an agent plans a similar action.
+
+```json
+{
+  "learning_type": "scar",
+  "title": "Always validate UUID format before DB lookup",
+  "severity": "medium",
+  "counter_arguments": ["Internal-only tools may trust input", "UUIDs from trusted sources are pre-validated"]
+}
+```
+
+**Required fields:** title, description, severity, counter_arguments (2+)
+
+See [Scars](/docs/concepts/scars) for details.
+
+## Wins
+
+**Approaches that worked well.** Capture what succeeded so you can replicate it.
+
+```json
+{
+  "learning_type": "win",
+  "title": "Parallel agent spawning cut review time by 60%",
+  "problem_context": "Code review of 500-line PR was taking too long with sequential analysis",
+  "solution_approach": "Spawned 3 agents in parallel: one for logic, one for tests, one for security"
+}
+```
+
+**Required fields:** title, description
+
+## Patterns
+
+**Reusable strategies.** Document approaches that work in specific contexts.
+
+```json
+{
+  "learning_type": "pattern",
+  "title": "5-Tier Test Pyramid for MCP Servers",
+  "applies_when": ["shipping MCP servers to npm", "pre-release verification"]
+}
+```
+
+**Required fields:** title, description
+
+## Anti-Patterns
+
+**Approaches that seem good but aren't.** Document why a seemingly reasonable approach fails.
+
+```json
+{
+  "learning_type": "anti_pattern",
+  "title": "Don't use console.log in MCP servers",
+  "description": "MCP uses stdio for JSON-RPC. Any console.log corrupts the transport. Use console.error for diagnostics."
+}
+```
+
+**Required fields:** title, description
+
+## Severity Levels
+
+Severity applies to scars and determines surfacing priority:
+
+| Level | Meaning | Example |
+|-------|---------|---------|
+| `critical` | Data loss or security risk | "Never store API keys in git" |
+| `high` | Significant time waste or user impact | "Done != Deployed != Verified" |
+| `medium` | Moderate friction or repeated issue | "Always validate UUIDs before DB lookup" |
+| `low` | Minor optimization or preference | "Use descriptive branch names" |
diff --git a/apps/docs/content/docs/concepts/meta.json b/apps/docs/content/docs/concepts/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Concepts",
+  "pages": ["index", "scars", "sessions", "threads", "learning-types", "tiers"]
+}
diff --git a/apps/docs/content/docs/concepts/scars.mdx b/apps/docs/content/docs/concepts/scars.mdx
@@ -0,0 +1,66 @@
+---
+title: Scars
+description: How GitMem captures and surfaces mistakes as institutional memory.
+---
+
+# Scars
+
+A **scar** is a mistake captured as institutional memory. When an AI agent encounters a problem, the lesson is recorded as a scar so that future agents (or future sessions of the same agent) don't repeat it.
+
+## How Scars Work
+
+1. **Something goes wrong** — A deployment fails, a bug slips through, a wrong assumption costs time
+2. **The scar is created** — The lesson is captured with title, description, severity, and counter-arguments
+3. **Future recall surfaces it** — When an agent plans a similar action, the scar appears automatically
+
+## Scar Anatomy
+
+```json
+{
+  "learning_type": "scar",
+  "title": "Done != Deployed != Verified Working",
+  "description": "Marking a task as done after committing code is not enough. The full loop is: commit → push → deploy → verify the service is running and accessible.",
+  "severity": "high",
+  "scar_type": "process",
+  "counter_arguments": [
+    "For local-only changes, deployment verification is unnecessary",
+    "In CI/CD pipelines, deployment may be automatic"
+  ]
+}
+```
+
+### Required Fields
+
+| Field | Purpose |
+|-------|---------|
+| `title` | Short, memorable name for the lesson |
+| `description` | Detailed explanation of what went wrong and how to avoid it |
+| `severity` | `critical`, `high`, `medium`, or `low` |
+| `counter_arguments` | At least 2 reasons why someone might reasonably ignore this scar |
+
+### Scar Types
+
+| Type | Decay | Use When |
+|------|-------|----------|
+| `process` | Never | The lesson is about how to work (e.g., "always run tests before pushing") |
+| `incident` | 180 days | A specific incident that may become less relevant over time |
+| `context` | 30 days | Temporary context (e.g., "API X is down, use fallback") |
+
+## Counter-Arguments
+
+Every scar **requires** at least 2 counter-arguments. This prevents scar accumulation from becoming a burden. Counter-arguments document when it's reasonable to ignore the scar.
+
+Good counter-arguments:
+- Describe specific scenarios where the scar doesn't apply
+- Acknowledge trade-offs (speed vs safety)
+- Note when the underlying cause has been fixed
+
+## The Confirm Protocol
+
+When scars are surfaced via `recall`, the agent must **confirm** each one before proceeding:
+
+- **APPLYING** — "I've accounted for this lesson" (with evidence)
+- **N_A** — "This scar doesn't apply to my current situation" (with reasoning)
+- **REFUTED** — "I'm deliberately overriding this scar" (acknowledging risk)
+
+This ensures scars are actively considered, not just passively displayed.