Product Manual

The reference: core concepts, the daily workflow, review mode, team features, and every tool. For setup, see the Quick Start.

What is aswritten?

aswritten lets you install human expertise into AI and verify where every claim comes from. It gives your AI a structured, version-controlled perspective — an expert’s decisions, methodology, rationale, and relationships — so it thinks like that expert 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 installed expertise and citing the source.

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

Core Concepts

Expertise as a Knowledge Graph

Expertise is the sum of what you know — 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, an aswritten perspective 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

Your Perspective

When you start a session, your AI loads your perspective — a structured snapshot of the knowledge graph that grounds every response. The perspective 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 the pipeline assembles transactions into your perspective. Extraction runs inside the remember call (~2-3 minutes); memory and transactions commit together atomically, and a PR opens for review. The full walkthrough is in the Quick Start; the technical detail is in the FAQ.

Daily Workflow

Session Start: Perspective

Every session begins with loading the perspective. Your AI calls perspective to load the current snapshot. This grounds the entire session — without it, responses are generic.

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

aswritten context — Perspective 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. You review the draft — memories are closer to PRs than commits — then the save runs extraction and opens a PR.

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: Cite

Cite takes any text — a blog post, a pitch deck, a status report — and checks every claim against the knowledge graph. 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

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:

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

Finding Open Reviews

Call review (no args) to see PRs waiting for your review. Pick one and call review with the PR number.

Post-Merge Doc Check

After merging, the system can suggest which documents may need updating based on the merged knowledge.

Multi-Repo and Team Features

Multiple Repositories

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

Directory-Scoped Perspective

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

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

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

Plans

Expert, Team, and Organization — what each includes and how upgrades work is on the Pricing page. Manage your plan with manage-account; check usage with check-budget.

The Ontology

The knowledge graph uses an RDF ontology that defines entity types, relationships, and constraints. Call ontology to see the current schema. Organizations can extend the base ontology for domain-specific needs — contact us for enterprise customization.

File Structure

.aswritten/
├── memories/          # Source documents (markdown)
├── tx/                # Extracted transactions (SPARQL)
├── manifest.json      # Pipeline state (managed automatically)

ASWRITTEN.md               # AI behavioral protocol

Tool Reference

Core tools

These are the five you use every day:

Tool	Purpose	When to Use
`perspective`	Load your perspective	Session start, after branch switch, after extraction completes
`cite`	Verify text against expertise	Before publishing, checking AI output
`introspect`	Find knowledge gaps	Before saving memories, assessing coverage
`remember`	Save knowledge to expertise	After decisions, interviews, discussions
`review`	Review and refine knowledge PRs	When extraction produces a PR awaiting review

Account and repo management

Tool	Purpose	When to Use
`init-repo`	Initialize repo for expertise	First-time setup
`manage-repos`	Install GitHub App	Connecting new repos
`list-repos`	See connected repos	Before switching repos
`switch-repo`	Change active repository	Multi-repo workflows
`manage-account`	Upgrade plan, add API key	Account management
`check-budget`	View API usage	Monitoring usage

Tool	Purpose	When to Use
`share`	Share perspective with another user	Onboarding teammates, cross-org sharing
`import`	Import shared perspective	Receiving shared knowledge
`forget`	Retract knowledge from a perspective	When knowledge is outdated or incorrect
`ontology`	View RDF schema	Understanding graph structure

BYOK (Bring Your Own Key): add your own OpenRouter API key via manage-account to avoid platform usage limits.