Manage Project Notes

When to use

Persist context about a project across sessions (briefs, known issues, changelogs)
Read what a previous session documented about a project
Track changes over time with full version history

How it differs from metadata documents

Metadata documents are deployment snapshots — frozen copies of config.ts and workflow JSON archived when you deploy. They cannot be updated after deployment. Project notes are living knowledge — updated any time, independently versioned, meant to accumulate context over the project’s lifetime. Multiple agents can read and write the same project’s documents across sessions.

Prerequisites

codika CLI installed and authenticated
A project ID

Commands

Upsert a document

Create a new document type or update an existing one. First call creates v0.0.0, subsequent calls increment the patch version.

codika notes upsert <projectId> --type <type> --summary <summary> [options]

List documents

codika notes list <projectId> [--type <type>] [options]

Get a document

codika notes get <projectId> --type <type> [options]

Options

Upsert options

Flag	Description
`--type <type>`	(Required) Document type ID (lowercase with hyphens)
`--summary <summary>`	(Required) What changed in this version
`--title <title>`	Document title (defaults to type ID)
`--content <content>`	Markdown content
`--file <path>`	Read content from a file instead of `--content`

Get options

Flag	Description
`--type <type>`	(Required) Document type ID
`--target-version <version>`	Get a specific version (e.g. `0.1.0`)
`--history`	Show all versions
`--api-key <key>`	API key override
`--json`	JSON output

What happens on upsert

If no document of that type exists for the project, creates version 0.0.0
If a current version exists, increments patch (0.0.0 -> 0.0.1)
Marks the previous version as superseded (immutable, still queryable)
Updates the version history

Versioning

Patch (default): 0.0.0 -> 0.0.1 -> 0.0.2
Minor (--major-change): 0.0.5 -> 0.1.0
Previous versions are never deleted — full history is preserved

Examples

Record a project brief:

codika notes upsert proj-abc123 \
  --type brief \
  --title "Project Brief" \
  --content "This project automates invoice processing for SMBs..." \
  --summary "Initial brief"

Update from a file:

codika notes upsert proj-abc123 \
  --type known-issues \
  --file ./notes/known-issues.md \
  --summary "Added timeout issue"

List all documents:

codika notes list proj-abc123

Read a document:

codika notes get proj-abc123 --type brief

View version history:

codika notes get proj-abc123 --type known-issues --history

Output

Upsert success:

Created brief -> v0.0.0
  Document ID: 019...
  Project:     proj-abc123

List:

Project notes for project proj-abc123:

  brief  v0.0.0  "Project Brief"
    Initial brief  (45 words)
  known-issues  v0.0.3  "Known Issues"
    Added timeout issue  (120 words)

2 document(s)

Type	Purpose
`brief`	What the project does, who it’s for, key decisions
`known-issues`	Bugs, edge cases, gotchas discovered during development
`changelog`	What changed and why across deployments
`debugging-log`	Diagnostic trail for ongoing issues
`deployment-notes`	Current deployment state and configuration
`architecture`	Key architectural decisions and rationale

Agent workflow patterns

Start of session: read existing context

codika notes list $PROJECT_ID
codika notes get $PROJECT_ID --type brief
codika notes get $PROJECT_ID --type known-issues

After building/deploying: record what you did

codika notes upsert $PROJECT_ID --type changelog \
  --content "v2: Added retry logic, increased timeout to 60s" \
  --summary "v2 deployment" --agent-id "use-case-builder"

After debugging: document the fix

codika notes upsert $PROJECT_ID --type debugging-log \
  --content "Timeout on large PDFs. Root cause: token limit. Fix: chunking." \
  --summary "Fixed PDF timeout"

Diagnosing issues: check history

codika notes get $PROJECT_ID --type changelog --history

Error handling

Error	Cause	Fix
”API key is required”	Not authenticated	Run `codika login`
”Project not found”	Invalid project ID	Verify with `codika get project <id>`
”documentTypeId must be lowercase”	Invalid type format	Use lowercase with hyphens
”content is required”	Missing content	Provide `--content` or `--file`
”content must be less than 500,000 characters”	Content too large	Split into multiple documents

Exit codes

Code	Meaning
`0`	Success
`1`	Failure

Overview

Setup

Build

Deploy

Operate

When to use

How it differs from metadata documents

Prerequisites

Commands

Upsert a document

List documents

Get a document

Options

Upsert options

Get options

What happens on upsert

Versioning

Examples

Output

Suggested document types

Agent workflow patterns

Start of session: read existing context

After building/deploying: record what you did

After debugging: document the fix

Diagnosing issues: check history

Error handling

Exit codes

​When to use

​How it differs from metadata documents

​Prerequisites

​Commands

​Upsert a document

​List documents

​Get a document

​Options

​Upsert options

​Get options

​What happens on upsert

​Versioning

​Examples

​Output

​Suggested document types

​Agent workflow patterns

​Start of session: read existing context

​After building/deploying: record what you did

​After debugging: document the fix

​Diagnosing issues: check history

​Error handling

​Exit codes

When to use

How it differs from metadata documents

Prerequisites

Commands

Upsert a document

List documents

Get a document

Options

Upsert options

Get options

What happens on upsert

Versioning

Examples

Output

Suggested document types

Agent workflow patterns

Start of session: read existing context

After building/deploying: record what you did

After debugging: document the fix

Diagnosing issues: check history

Error handling

Exit codes