How the store works

@runtime_checkable
class Store(Protocol):
    def read_file(self, path: str) -> str | None: ...
    def write_file(self, path: str, content: str) -> None: ...
    def delete_file(self, path: str) -> None: ...
    def list_decisions(self) -> list[str]: ...
    def read_decision(self, file_stem: str) -> str | None: ...
    def read_decisions(self, stems: list[str]) -> dict[str, str | None]: ...

<repo>/.nauro/config.json        # committed: {mode,id,name,schema_version[,server_url]}

~/.nauro/                        # NAURO_HOME (default)
  registry.json                  # project registry (v2: keyed by ULID)
  config.json                    # user config (telemetry, search.embeddings)
  projects/<id>/                 # the project store
    project.md
    state_current.md
    stack.md
    open-questions.md
    .decision-hashes.json        # exact-dup hash index
    decisions/
      001-initial-setup.md
      042-use-postgres.md        # NNN-slug.md
    snapshots/
      v001.json                  # point-in-time JSON captures

---
date: 2026-04-16
version: 1
status: active
confidence: high
decision_type: infrastructure
---

# 042 — Use Postgres

## Decision

Use Postgres for the primary datastore...

## Rejected Alternatives

### SQLite

Single-writer ceiling won't hold under concurrent API load.

corpus = [f"{d.title} {d.rationale}" for d in decisions]
corpus_tokens = bm25s.tokenize(corpus, stopwords="en", stemmer=_stemmer, show_progress=False)

retriever = bm25s.BM25()
retriever.index(corpus_tokens, show_progress=False)

k = min(limit, len(decisions))
query_tokens = bm25s.tokenize([query], stopwords="en", stemmer=_stemmer, show_progress=False)
results, scores = retriever.retrieve(query_tokens, k=k, show_progress=False)
# ... only hits with score > 0 are kept (the loop breaks on the first score <= 0)

bm25_hits = bm25_retrieve(decisions, query_text, top_k=top_k, stopwords=stopwords)
if not use_embeddings:
    return bm25_hits

from nauro_core.embeddings import embedding_pool

active = [d for d in decisions if d.status is DecisionStatus.active]
pool = embedding_pool(active, query_text, top_k=top_k)
if not pool:
    return bm25_hits  # fail-open: BM25-only

seen = {hit["number"] for hit in bm25_hits}
by_num = {d.num: d for d in active}
augmented = list(bm25_hits)
for num in pool:
    if num in seen:
        continue
    d = by_num.get(num)
    if d is None:
        continue
    seen.add(num)
    augmented.append({"number": d.num, "title": d.title,
                      "similarity": None, "rationale_preview": d.rationale[:200]})

def resolve_embeddings_flag() -> bool:
    env_value = os.environ.get(NAURO_EMBEDDINGS_ENV)  # NAURO_EMBEDDINGS
    if env_value is not None:
        return _is_truthy(env_value)
    return _is_truthy(get_config(_EMBEDDINGS_CONFIG_KEY))  # "search.embeddings"
    # _is_truthy: True for bool True, or "1"/"true"/"yes"/"on" (case-insensitive); default OFF

def write_file(self, path: str, content: str) -> None:
    target = self._store_path / path
    target.parent.mkdir(parents=True, exist_ok=True)
    lock = target.with_name(target.name + ".lock")
    with FileLock(str(lock)):
        target.write_text(content)

def atomic_write_text(path: Path, text: str, *, mode: int | None = None) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    tmp = path.with_suffix(".tmp")
    tmp.write_text(text)
    if mode is not None:
        os.chmod(tmp, mode)   # e.g. 0o600 before the rename
    os.replace(tmp, path)     # atomic on a single filesystem; no fsync

files = {}
for md in sorted(store_path.glob("*.md")):
    files[md.name] = md.read_text()
decisions_dir = store_path / DECISIONS_DIR
if decisions_dir.exists():
    for md in sorted(decisions_dir.glob("*.md")):
        files[f"{DECISIONS_DIR}/{md.name}"] = md.read_text()

snapshot = serialize_snapshot(
    timestamp=datetime.now(timezone.utc).isoformat(),
    trigger=trigger, trigger_detail=trigger_detail,
    files=files, version=next_version,
)
out_path = snapshots_dir / f"v{next_version:03d}.json"
out_path.write_text(json.dumps(snapshot, indent=2) + "\n")
_prune_snapshots(snapshots_dir)

Events (only these, with only these properties):
  cli.command_invoked  { command, success, duration_bucket, nauro_version, os }
  mcp.tool_called      { tool_name, transport, success, duration_bucket }
  sync.completed       { snapshot_count, duration_bucket, bytes_bucket }
  project.created      { schema_version }

Never sent: decision titles, rationale, content; file paths;
  repo names; project names; MCP tool arguments and return values;
  stack traces; command-line arguments; IP address; geolocation.