Quick Start

What You Need

  • Claude Code (Anthropic’s CLI) or Claude Desktop or any MCP compatible AI client.
  • A GitHub account (personal or org)
  • A GitHub repo (or multiple) you want to give AI memory.

Setup with Claude Code (5 minutes)

1. Add the MCP server

Run this once from anywhere — it registers aswritten across all your projects:

claude mcp add --scope user --transport http aswritten https://api.aswritten.ai/mcp

2. Authenticate

Open Claude Code in any project directory and run /mcp. You’ll see the aswritten server listed. Select it to authenticate — this opens a browser window. Choose the Individual plan for a free trial, or team if you want to work with others right away.

3. Restart Claude Code

Quit and reopen Claude Code so the authenticated MCP connection takes effect.

4. Onboard your first repo

Start Claude Code in your project directory and say “aswritten”. Claude will walk you through:

  1. Connect GitHub — Install the aswritten GitHub App and select which repos to connect
  2. Initialize — Switch to your current repo and scaffold collective memory files (ASWRITTEN.md, GitHub Actions, story templates) via a commit to your default branch
  3. First memory — Claude interviews you about the project and saves your first memory

After the first memory is saved, GitHub Actions run extraction (takes ~5-10 minutes). Once the PR merges, Claude can compile your organizational worldview and work with full context.

Setup with Claude Desktop

1. Add the MCP server

Go to Settings → Connectors and add the aswritten server URL:

https://api.aswritten.ai/mcp

2. Authenticate

Press Connect. This opens a browser window — choose the Individual plan for a free trial, or team if you want to work with others right away.. Return to Claude Desktop after authenticating.

3. Onboard your first repo

Same as Claude Code — say “aswritten” and Claude walks you through connecting GitHub, initializing your repo, and creating your first memory.

4. Add ASWRITTEN.md to your project

Claude Desktop doesn’t automatically read repo files like Claude Code does. To give Claude the behavioral instructions it needs:

  1. Create a Project in Claude Desktop for your repo (sidebar → Projects → New Project)
  2. Open the ASWRITTEN.md file from your repo on GitHub (the init step will give you a direct link)
  3. Copy its contents into the Project’s custom instructions

This gives Claude Desktop the same collective memory directives that Claude Code picks up automatically from the file in your repo.

Any MCP compatible AI tool (Github Copilot, N8N, etc)

1. Add the MCP server

Add https://api.aswritten.ai/mcp as a HTTP MCP server.

2. Authenticate

Authenticate the mcp server — this opens a browser window. Choose the Individual plan for a free trial, or team if you want to work with others right away.

3. Restart

You may need to restart your AI so the authenticated MCP connection takes effect.

4. Onboard your first repo

Start your AI tool and say “aswritten”. Claude will walk you through:

  1. Connect GitHub — Install the aswritten GitHub App and select which repos to connect
  2. Initialize — Switch to your current repo and scaffold collective memory files (ASWRITTEN.md, GitHub Actions, story templates) via a commit to your default branch
  3. First memory — Claude interviews you about the project and saves your first memory

After the first memory is saved, GitHub Actions run extraction (takes ~5-10 minutes). Once the PR merges, Claude can compile your organizational worldview and work with full context.

What Happens During Onboarding

Claude walks you through this entire process, but here’s what to expect:

First memory creation. Claude interviews you about your project — what it does, key decisions you’ve made, who’s involved, what’s in progress. You talk naturally; Claude drafts a memory document from the conversation and asks you to approve it before saving. The memory is committed to a branch in your repo under .aswritten/memories/.

Extraction pipeline. After the memory saves, GitHub Actions kick in automatically. An LLM reads your memory and extracts structured knowledge (facts, decisions, actors, relationships) as RDF transactions. A PR opens with the extracted knowledge and regenerated story documents. This takes 5-10 minutes.

PR review and merge. The PR shows exactly what was extracted — you can see which facts the system pulled from your words. Review and merge when ready. This is your audit trail: every piece of organizational knowledge traces back to a specific memory from a specific person.

Compile. After merging, Claude compiles your worldview — a structured snapshot of everything your organization knows. This is what grounds Claude’s responses going forward. Instead of generic answers, Claude draws on your documented decisions, strategy, and context.

Introspect. Claude can analyze what’s documented vs. what’s missing. It surfaces knowledge gaps by domain and suggests questions to fill them. This is how collective memory grows intentionally — not just from what you happen to mention, but from what the system identifies as undocumented.

The loop. From here, the pattern repeats naturally: you work, decisions come up, Claude offers to save them, extraction runs, the worldview updates, and Claude’s behavior shifts to reflect what you’ve documented. Each memory makes every future session smarter.

Daily Use

Once set up, Claude automatically compiles your worldview at session start. As you work:

  • Decisions come up → Claude offers to save them as memories
  • You ask questions → Answers are grounded in your documented knowledge, not hallucinated
  • Gaps surface → Claude identifies what’s undocumented and suggests who to ask
  • Stories regenerate → Blog posts, status reports, and docs stay current with your worldview

Upgrading from the Old Setup

If you previously had aswritten configured via .mcp.json and CLAUDE.md in a repo:

  1. Delete the old aswritten entry from your .mcp.json
  2. Remove any aswritten-related instructions from CLAUDE.md
  3. Follow the setup steps above — the new flow handles everything

The init step will re-scaffold ASWRITTEN.md and .mcp.json automatically.

Multiple Repos

aswritten works across repos and organizations. Use switch-repo to change which repo Claude is working with. Each repo stores its own collective memory.

Feedback

Share interesting sessions via Claude Code’s /export command. Bug reports and feedback welcome — the MCP proxy auth is brand new.

This site uses Just the Docs, a documentation theme for Jekyll.