Skip to content
familiarfamiliarfamiliar

1. What core is

Baseline: core 1.0.2 · state schema 1.0 · extension contract 1.1 · install record schema 1.1 Scope: familiar core only, the familiar-workspace/ folder as it ships. The extension contract appears here as the interface that core defines. No extension is described.

This manual describes how familiar core works: each mechanism, where it lives, what enforces it, and where it stops. docs/using-familiar.md is the user guide, and INSTALL.md has the install and update steps. If this manual disagrees with the files in your copy, the files are right. Please report the difference.

familiar core is a memory and routing layer for coding agents. It works on several agents, and it stays inside one project folder. It is a set of plain files:

  • Markdown rules and skills
  • two JSON schemas
  • a ready-made entry file for each agent

All of it ships inside one folder, familiar-workspace/. It gives that folder a lasting memory that is the one source of truth. It also gives the agent a fixed way to load only the instructions that a request needs.

Three claims define core. Each one has a mechanism in the files:

  1. One home per fact. Project state lives in named files, each with a stated update rule (§6). Everything else, such as reports, dashboards and briefings, is a view. A view never overrides its source.
  2. Load after routing, not before. The bootstrap allows a few bounded reads at startup, for preferences and binding (§4.1). The agent then selects one route and loads exactly one skill and the context it declares (§4, §5).
  3. Never claim a capability that has not been proven. Capability state uses five fixed values, and none of them implies a fallback. active means that a released check passed (§10).

Core is neutral. It ships nothing for a specific field and names no extension. The bootstrap contains no field-specific words, and the release checks confirm this. A specialty arrives only through the extension contract (§11), which core discovers without knowing any extension in advance.

What core is not

Section titled “What core is not”
  • Not a program that runs. Core routing and memory are files that the agent reads. There is no install step: you copy familiar-workspace/ and use it as it is. Document and PDF features (deck and document builds, PDF extraction) still need Python. Without Python, the agent tells you that those features do not work. It does not pretend to fall back.
  • Not an enforcement layer. Core states rules, and the model follows them. The optional guards in familiar-hooks add a mechanical check that helps enforce some rules, but they are not a guarantee. The guards are not part of the core download.
  • Not for several writers at once. familiar supports one active writer at a time. The stale-write protocol (§6.3) detects a conflict. It does not merge one.