Product Manual

What is aswritten?

aswritten is collective memory for AI. It gives your AI tools a structured, version-controlled worldview — your organization’s decisions, strategy, rationale, and relationships — so they think like your org instead of hallucinating.

The product is an MCP server. You connect it to Claude Code, Claude Desktop, or any MCP-compatible AI tool. From there, you talk to your AI normally. aswritten works underneath — grounding responses in what your organization actually knows.

Everything lives in your Git repo. Memories go in, knowledge comes out, and every fact traces back to a person and a context.

Getting Started

See the Quick Start for installation and first-time onboarding.

Core Concepts

Collective Memory

Collective memory is the sum of what your organization knows — not just documents, but decisions, reasoning, relationships, and context. aswritten stores this as an RDF knowledge graph in your Git repo.

Unlike a wiki or a knowledge base, collective memory is:

  • Narrative-driven — memories are written in natural language, preserving nuance and reasoning
  • Provenance-tracked — every fact traces back to who said it, when, and in what context
  • Version-controlled — knowledge branches, merges, and has full audit history via Git
  • Machine-readable — the RDF graph structure means AI tools can query and reason over it

The Worldview

The worldview is a compiled snapshot of collective memory. When you start a session, your AI compiles the worldview and uses it to ground every response. The worldview covers domains like Strategy, Product, Architecture, Organization, and Proof.

Conviction Levels

Every claim in the graph carries a conviction level — how settled the knowledge is:

  • notion — First mention, casual observation, untested hypothesis. Easily moved.
  • claim — Asserted, still validating. Committed but moveable with evidence.
  • decision — Settled. Requires significant counter-evidence to revisit.
  • principle — Bedrock. Career-arc level conviction.

Memories and Transactions

A memory is a source document — a conversation transcript, meeting notes, a written reflection. Memories live in .aswritten/memories/.

A transaction is the structured knowledge extracted from a memory — RDF/SPARQL statements that update the graph. Transactions live in .aswritten/tx/.

The relationship: you write memories (natural language), the extraction pipeline produces transactions (structured knowledge), and compilation assembles transactions into a worldview.

Daily Workflow

Session Start: Compile

Every session begins with compilation. Your AI calls compile to load the current worldview. This grounds the entire session — without it, responses are generic.

After compiling, the AI produces a context callout showing what it knows:

aswritten context — Worldview loaded. Strong coverage in Strategy and Product. Architecture is sparse. No coverage of competitive landscape.

Saving Knowledge: Remember

When a decision is made, a perspective is shared, or important context comes up in conversation, the AI offers to save it as a memory.

The workflow:

  1. Draft — The AI drafts a memory from the conversation, preserving direct quotes and reasoning
  2. Review — You review and refine the draft. Memories are closer to PRs than commits
  3. Save — The memory commits to a topic branch in your repo
  4. Extract — GitHub Actions run extraction (5-10 minutes), producing SPARQL transactions
  5. PR Review — A PR opens showing exactly what was extracted
  6. Merge — You review and merge. The worldview updates on next compile

Finding Gaps: Introspect

Introspect analyzes what’s documented and what’s missing. It surfaces knowledge gaps by domain and suggests questions to fill them.

Modes:

  • analysis — Coverage metrics, structural health, domain breakdown
  • interview — Gaps formatted as questions you can answer to fill them
  • working_memory — Score a draft memory against identified gaps before saving

Verifying Content: Annotate

Annotate takes any text — a blog post, a pitch deck, a status report — and checks every claim against collective memory. It returns a coverage score and flags unsupported claims.

Use it to:

  • Verify a document before sending it externally
  • Find claims that should be saved as memories
  • Check whether your AI’s output is grounded or hallucinated

Scope finds concepts in collective memory relevant to a specific topic. Use it as a starting point for deep dives or to understand what the graph knows about a particular area.

Retrieving Sources: Memories

When you need the full source behind a fact — who said it, the original phrasing, the context — call memories with a topic. It returns the original memory files and their extracted transactions.

Content Generation

Stories and Templates

aswritten includes story templates — structured prompts that generate documents from collective memory. Templates specify audience, tone, and which compile layer to use.

Available templates include business plans, fundraising briefs, sales playbooks, case studies, and more. Call stories to see what’s available.

Registered Documents (Refraction)

Documents registered in .aswritten/refraction.yaml are tracked against the knowledge graph. When the graph changes, registered documents are checked for drift — places where the content no longer matches what the org knows.

To register a document:

  • Use the register tool with action add and the document path
  • Or edit .aswritten/refraction.yaml directly

Registered documents are automatically checked during PR reviews.

Refract: Detecting Drift

Refract analyzes how a knowledge change affects a specific document. It returns focus areas with severity levels:

  • high — Section would be misleading if not updated
  • medium — Section defensible but could be sharper
  • low — Optional enrichment

Review Mode

The Review Cycle

When a memory is saved and extracted, a PR opens. The review process uses an optometrist model — iterative convergence through shifts.

Phases:

  1. TX Summary — What this PR changes about what the org believes
  2. Zone Identification — Cluster changes by domain, pick 2-3 to exercise
  3. Test Document — Select a registered doc to test shifts against
  4. Baseline — Compare the document before and after the new knowledge
  5. Shifts — Generate 2-4 targeted perspective shifts. “Better through A or B?”
  6. Fact Review — Walk through extracted entities, conviction levels, relationships
  7. Wrap-up — Converged draft, review memory saved, merge

Finding Open Reviews

Call list_open_reviews to see PRs waiting for your review. Pick one and start the review process with start_review.

Post-Merge Refraction

After merging, registered documents are automatically checked for shifts. The system presents a summary of which documents need attention and at what severity.

Multi-Repo and Team Features

Multiple Repositories

aswritten works across repos. Each repo has its own collective memory. Use switch-repo to change which repo the AI is working with, or pass owner and repo to any tool call.

Directory-Scoped Compile

For client isolation — consultancies, agencies, or multi-tenant setups — use directory-scoped compilation. Each directory under your repo can have its own .aswritten/ ledger. Compile with dir=clients/acme to get that client’s worldview merged with the root.

Directory scoping is for data isolation, not topic organization. Use scope and introspect for semantic filtering.

Sharing Knowledge

Share collective memory with other users via share. The recipient gets a notification and can import the bundle into their own repo with import.

Seats and Plans

  • Individual — Free trial. One repo, one user.
  • Team ($400/mo) — 10 seats included, $200/additional seat. Self-serve onboarding.
  • Professional ($4K/mo + $15K SOW) — Consultant-led knowledge extraction. On-prem available for compliance (HIPAA, GDPR).

Manage your plan with manage-account. Check usage with check-budget.

The Extraction Pipeline

How It Works

  1. A memory file is pushed to a branch under .aswritten/memories/
  2. GitHub Actions trigger the injest-memories workflow
  3. An LLM reads the memory and produces SPARQL transactions
  4. Transactions are validated against the ontology
  5. Story templates regenerate based on the updated graph
  6. A PR opens with the memory, transactions, and regenerated stories
  7. You review and merge
  8. The worldview updates on next compile

Timing

Extraction takes 5-10 minutes. Do not recompile immediately after saving a memory — wait for the PR’s GitHub Actions to complete.

The Manifest

.aswritten/manifest.json tracks pipeline state — which memories have been processed, which transactions are current. This is managed automatically.

The Ontology

The knowledge graph uses an RDF ontology that defines entity types, relationships, and constraints. Call ontology to see the current schema.

Custom Ontology

Organizations can extend the base ontology for domain-specific needs. (Coming soon — contact us for enterprise customization.)

File Structure 

.aswritten/
├── memories/          # Source documents (markdown)
├── tx/                # Extracted transactions (SPARQL)
├── stories/           # Story templates (.story)
├── manifest.json      # Pipeline state
└── refraction.yaml    # Registered documents

.github/workflows/
├── injest-memories.yml    # Memory extraction
├── draft-stories.yml      # Story regeneration
└── validate-sparql.yml    # SPARQL validation

ASWRITTEN.md               # AI behavioral protocol

Tool Reference

Tool Purpose When to Use
compile Load organizational worldview Session start, after branch switch, after extraction completes
introspect Find knowledge gaps Before saving memories, assessing coverage
annotate Verify text against collective memory Before publishing, checking AI output
scope Navigate knowledge by topic Starting a deep dive, finding relevant concepts
memories Retrieve source documents Tracing provenance, reviewing originals
remember Save knowledge to collective memory After decisions, interviews, discussions
stories List content templates Before generating documents
register Manage document registry After creating docs that should track the graph
refract Detect document drift Pre-publish checks, after graph changes
start_review Review knowledge PRs When open reviews exist
list_open_reviews Find pending reviews Checking what needs attention
share Share memory with another user Onboarding teammates, cross-org sharing
import Import shared memory Receiving shared knowledge
switch-repo Change active repository Multi-repo workflows
init-repo Initialize repo for collective memory First-time setup
ontology View RDF schema Understanding graph structure
manage-repos Install GitHub App Connecting new repos
list-repos See connected repos Before switching repos
check-budget View API usage Monitoring usage
manage-account Upgrade plan, add API key Account management

Troubleshooting

“The worldview is empty”

You haven’t saved any memories yet, or extraction hasn’t completed. Save your first memory and wait for the GitHub Actions PR to merge.

“Compile returns sparse results”

Check if there are pending shares to import (import with no arguments). If not, use introspect in interview mode to identify what domains need memories.

Extraction is taking too long

Check the GitHub Actions tab on your repo. Extraction typically takes 5-10 minutes. If it’s stuck, check the workflow logs.

“I don’t have a GitHub account”

You need one today. GitHub abstraction for non-technical users is on the roadmap.

BYOK (Bring Your Own Key)

Add your own OpenRouter API key via manage-account to avoid platform usage limits.

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