files — state on disk and in SQLite

Created by npc init, or implicitly by Runtime.for_repo() through ensure_repo_ready(). The five subdirectories under .npcagent/ are fixed in _NPCAGENT_SUBDIRS; everything deeper appears on demand.

Only three of these are gitignored — .npcagent/db/, .npcagent/memory/ and .npcagent-worktrees/. That is a deliberate asymmetry: project files, plans and ledgers are meant to be committable, so a plan artefact and its Stage 2 expansion can be reviewed in a pull request like any other document. Databases, working memory and scratch worktrees are not.

Three of these directories sit in the middle of a three-level search stack — bundled catalog first, user directory second, repository directory third, with later entries overriding earlier ones. That applies identically to workflows, skills and prompts, so a repository can shadow a bundled workflow without editing the installation.

SQLite through aiosqlite, with SQLAlchemy 2.0 async sessions. Schema is owned by Alembic — twelve migrations in a linear chain — and the ORM models exist to mirror it, not to create it. Tests build the schema from the models via Base.metadata.create_all; production never does.

Migrations run in-process, not through a subprocess, and in a dedicated thread. The reason is stated in repo_init.py: Alembic's env creates an async engine via asyncio.run, but Runtime construction is synchronous and may happen while an event loop is already running. A short-lived thread gives Alembic a context with no active loop.

Settings resolve through pydantic-settings with extra = "forbid" — an unknown key is an error, not a warning. Sources in decreasing priority: constructor arguments, environment, .env, the TOML file, then file secrets. The TOML path is $NPCAGENT_CONFIG_FILE if set, otherwise ~/.npcagent/config.toml.

Only two of these are written by npc model: default_cli_provider and default_model. Everything else is environment or hand-edited TOML.

Beyond the settings prefix, a number of variables are read directly at their point of use. They are listed here because several of them are the only way to reach the behaviour they control.

A memory read walks four scopes, most specific first, and returns the first hit. Symlinked paths are skipped on read and rejected outright on write.

1 · agent

<repo>/.npcagent/agents/<agent>/

2 · project

<repo>/.npcagent/projects/<project>/memory/ — the default write level

3 · repo

<repo>/.npcagent/memory/

4 · global

~/.npcagent/memory/ — always present, re-evaluated at call time so a changed $HOME is honoured

Within any scope directory the layout is the same: a mutable current.md, dated YYYY-MM-DD.md dailies, an archive/, and — once facts have been extracted — semantic/facts.json. Writes take an fcntl.flock. Compaction rolls dailies older than one day into weekly/YYYY-WNN.md and weeklies older than seven days into monthly/YYYY-MM.md, moving originals to archive/. It is idempotent, because archived files are no longer discoverable.

Entries are filed under one of six closed categories: decision, preference, commitment, constraint, open_loop, fact.

Injection is cache-shaped

Memory reaches an agent as a single XML-ish block appended to the system prompt after a static prefix, with an explicit cache breakpoint between them:

The block is capped at 32,000 characters and truncated with a <truncated/> marker. On the way back out, scrub_memory_tags() strips these tags from agent output before it is displayed or written to the event log, and a StreamingScrubber handles the case where a tag is split across two stream chunks.

• npc(1)
• npc-commands(1)
• runtime(7)
• workflow(7)
• planner(7)
• plugins(7)