Code Project Documentation

Basic Memory turns your project's docs/ folder into a shared knowledge base that both you and your AI can read and write. Architecture decisions, API docs, coding patterns -- they all live as markdown files right next to your code, connected through a knowledge graph that makes them easy to find and keep current.

Setting Up

Create a project for your documentation — ask your AI, and it works the same on cloud and local:

Create a new project called "my-project-docs"

The AI calls create_memory_project behind the scenes.

Cloud is a great home for project docs: browse and edit them in the web app, give the whole team (and their agents) access, and publish any page externally with a share link. Prefer docs living inside the repo? On a local install, point the project at your docs/ folder instead:

bm project add my-project ~/code/my-project/docs

That's it. Your AI assistant can now read and write documentation in that project. You'll end up with a structure like this:

my-project/
├── src/
├── tests/
├── docs/                  # Your Basic Memory knowledge base
│   ├── architecture/
│   ├── decisions/
│   ├── guides/
│   ├── patterns/
│   └── api/
└── README.md

Key Documentation Patterns

The real power is that you can just tell your AI what to document and it handles the structure.

Architecture Decision Records

When your team makes a significant technical choice, capture it:

"We just decided to use PostgreSQL instead of MongoDB for the financial app. Write an ADR explaining why -- ACID compliance, analytical queries, and team SQL experience were the main factors."

Your AI creates a well-structured decision record with the context, rationale, alternatives considered, and consequences. The note gets linked to related architecture docs automatically.

If you want all your ADRs to follow the same structure, ask the AI to create a schema:

"Create a schema for our architecture decision records. They should always record a status, context, decision, and consequences."

The AI writes a schema note like this:

---
title: ADR
type: schema
entity: adr
version: 1
schema:
  status: string, current decision status
  context: string, background and problem statement
  decision: string, what was decided
  consequences(array, outcomes of the decision): string
  supersedes?: ADR, previous decision this replaces
settings:
  validation: warn
---

Schema fields are satisfied by observations — an ADR with - [status] accepted and - [decision] Use JWT tokens passes; markdown headings alone don't count (see Schema System). From that point on, every ADR the AI creates follows this structure. You can validate existing ones too:

bm schema validate adr

See the Schema System guide for full details on defining and using schemas.

API Documentation

"Document the authentication endpoints -- login, refresh, and logout. Include the request/response formats and error codes."

The AI creates API docs with practical details: endpoint paths, payload examples, error responses, and links to related concepts like rate limiting or token management.

You can set up a schema for API docs the same way you did for ADRs, so every endpoint doc has a consistent format.

Architecture Overviews

"Write up our system architecture. We have a React frontend, a FastAPI backend, and PostgreSQL. Everything runs in Docker on Kubernetes."

The AI produces an architecture overview with components, data flows, and relations to other docs like your database schema and deployment guide. As the system evolves, you update the doc in conversation:

"Add the new Redis caching layer to the architecture overview."

Notes are protected from accidental overwrites -- the AI uses incremental edits to update existing docs rather than replacing them, so you never lose content by mistake.

Finding and Reviewing Documentation

Basic Memory's search understands meaning, not just keywords. Ask for what you need in plain language:

"Find our docs about how we handle user authentication."

This finds notes about JWT validation, OAuth flows, and login endpoints -- even if none of them contain the exact phrase "user authentication." That's semantic search at work.

You can also search by specific note properties when you know what you're looking for:

"Show me all accepted ADRs."

"Find API docs tagged with authentication."

"What patterns have we documented for error handling?"

The AI combines the right filters for each: status on an ADR is an observation category, so it filters with categories=["status"]; tags and note types are frontmatter, filtered with metadata search. You can also use the tag: shorthand in searches, like tag:api or tag:security.

For a deeper dive, see Semantic Search.

Development Workflows

During Development

When you build something new, document it in the same conversation:

"Document the user preference system we just implemented."

When you're picking up where you left off:

"What do our docs say about the notification service? I need to extend it."

Before a Pull Request

Check whether your changes need doc updates:

"I changed how refresh tokens work. Do we have docs that need updating?"

The AI searches your knowledge base, finds the relevant API docs and architecture notes, and either updates them or tells you what needs attention.

Sprint Reviews

"Update our architecture overview with the changes from this sprint."

The AI reviews what's changed and makes targeted updates to the relevant docs.

Best Practices

1. Document decisions, not just implementations -- Capture the "why" behind choices. Six months from now, the reasoning matters more than the code.
2. Use schemas for recurring doc types -- ADRs, API docs, runbooks. Define the structure once and every doc of that type stays consistent.
3. Let relations do the linking -- When the AI writes relates_to [[Database Schema]], it creates a navigable connection in the knowledge graph. This is how you build docs that are easy to explore.
4. Keep docs next to code -- Version-controlled documentation in your repo means docs and code stay in sync through the same PR process.
5. Search before writing -- Ask the AI to check for existing docs before creating new ones. This prevents duplication and keeps your knowledge base clean.

Next Steps