Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/virsanghavi/axis/llms.txt

Use this file to discover all available pages before exploring further.

The project soul is the persistent, shared memory that makes every agent session coherent — even when no agent has worked on the project in weeks. Stored in .axis/instructions/ at the repo root, it carries the project’s goals, architecture decisions, coding conventions, and agent behavioral norms. Any agent that reads the soul at the start of a session arrives with the full mental model of the project, not a blank slate.
The hosted MCP server does not have access to your repository’s disk. get_project_soul and update_project_soul are local-only tools available on the @virsanghavi/axis-server stdio server. The hosted notepad (get_shared_context) is the hosted equivalent for live session context.

​
get_project_soul

Local only. get_project_soul reads soul files from the client’s disk. Use get_shared_context for live session context when on the hosted surface.
Loads the project soul: the combined content of .axis/instructions/context.md and .axis/instructions/conventions.md. Per the agent protocol, this is the first action in every agent session — non-negotiable regardless of how simple the task appears.
​
projectName
string
The project to load the soul for. Defaults to the auto-detected project from the active workspace root.
Returns: The combined content of context.md and conventions.md as a single string. The agent reads this before touching the job board, files, or anything else.

​
update_project_soul

Local only. update_project_soul writes to soul files on the client’s disk. The hosted server has no filesystem access.
Writes to the project soul files. Call this whenever the project’s architecture, stack, conventions, or shared API contracts change — so future sessions start with accurate context.
​
content
string
required
The new content to write to the soul file. The entire target file is replaced.
​
filename
string
Which file to write: context or conventions. Defaults to context.
​
projectName
string
The project to update the soul for. Defaults to the auto-detected project.

​
Soul file structure

The soul lives in .axis/instructions/ and is created when you run npx axis-init@latest in the repo root.
FilePurpose
context.mdProject overview, architecture decisions, core features, stack choices, and any shared API contracts.
conventions.mdCoding standards, naming conventions, test strategy, agent behavioral norms, and patterns to follow or avoid.
activity.mdActivity log — written automatically via update_shared_context, not directly via update_project_soul.

​
When to update the soul

Architecture changes

Whenever the tech stack, persistence layer, service topology, or module boundaries change — update context.md so future agents understand the current shape of the system.

New conventions

When a new coding standard, naming convention, or agent behavioral norm is established — update conventions.md so every future agent respects it without being told.

Major refactors & onboarding

After onboarding a new service, completing a major refactor, or migrating to a new pattern — the soul should reflect the post-refactor world, not the pre-refactor one.

Shared contract changes

When an API signature, token shape, database schema, or inter-service protocol changes — update the soul immediately so agents reading it after the change don’t generate code against the old contract.

​
Example soul content

The following shows a well-maintained context.md for the Axis project itself: 
# Project Context

## Overview
Axis is a multi-agent coordination layer for AI coding agents. It provides a
shared job board, advisory file locks, a live notepad, and code intelligence
over MCP. Two repos: `shared-context` (local server + CLI + Python SDK) and
`axis-frontend` (hosted product at useaxis.dev).

## Architecture
- Local MCP server: @virsanghavi/axis-server (stdio, ships to customers)
- Hosted MCP: https://useaxis.dev/api/mcp
- Persistence: Supabase (hosted) → direct Supabase (dev) → local JSON fallback
- Coordination facade: NerveCenter delegates to JobBoard, LockRegistry, etc.

## Core Features
- Shared job board with atomic claiming (SELECT FOR UPDATE SKIP LOCKED)
- Advisory file locks with tamper detection (content fingerprinting)
- Live shared notepad (in-memory, scoped to org/project)
- Vector + full-text + trigram search, fused and LLM-reranked (hosted Pro)

## Shared Contracts
- Token payload: { userId, role, exp } — callers must not read session.user.id
- Project identity derived from nearest .axis/axis.json or repo folder name
- Org scoping via X-Axis-Org header or AXIS_ORG_ID env var
And a conventions.md: 
# Conventions

## Code Style
- Runtime: Bun. Use `bun test` for tests, `bun run` for scripts.
- TypeScript strict mode throughout.
- No `any` in new code — use `CoordinationContext` for the typed slice.

## Agent Norms
- Always call get_project_soul first — no exceptions.
- Always call finalize_session when the user's request is fully complete.
- Use guarded_write instead of direct writes when holding a lock.
- Post an update_shared_context note after every meaningful state change.

## Testing
- Unit tests live in tests/. Keep CoordinationContext mocks all-optional.
- CI: bun test + eslint + tsc --noEmit (audit #8 in progress).

​
Session start protocol

The agent protocol requires get_project_soul as the first action in every session. Here is the correct opening sequence:
1

Load the soul

get_project_soul()
Read the returned context and conventions before doing anything else.
2

Check the board and locks

list_jobs()
list_locks()
Understand what’s already in flight before claiming or posting work.
3

Read the notepad

get_shared_context()
See what teammates did before this session started.
4

Begin work

Claim a job, post new jobs, or start work — with full context.

Build docs developers (and LLMs) love

Get started for freeTalk to us