foghorn stale --exit-code   # Fails CI if any agent decision is based on stale facts

flowchart LR
    A[Agent records Fact\nsubject · predicate · object] --> B[Agent records Decision\ndepends_on Fact IDs]
    B --> C[foghorn commit\nWorldCommit snapshot]
    C --> D{Fact changes\nnew triple added}
    D --> E[diff_commits\ndetects added/removed]
    E --> F[compute_staleness\nfinds affected decisions]
    F --> G[StalenessAlert\nimpact_score ranked]

pip install foghorn-ai

from foghorn.repo import WorldRepo

repo = WorldRepo.init(".foghorn/world.db")

# Record facts your agent is relying on
f = repo.add_fact("Redis", "is-appropriate-for", "rate-limiting", confidence=0.95)
pg = repo.add_fact("Postgres", "is-primary-db", "yes")

# Record a decision that depends on those facts
repo.decide(
    "chose-redis-for-rate-limiting",
    "Redis is fast enough for our rate-limiting needs at current scale.",
    depends_on=[f.id],
)

commit = repo.commit("Initial architecture decisions")
print(commit.id)  # e.g. "a3f8b2c1d4e5f6a7"

# Later — the world changed: retract the old fact, add the replacement
repo.retract_fact(f.id)
repo.add_fact("Redis", "replaced-by", "Valkey")
repo.commit("Redis EOL notice")

# Which decisions are now stale?
alerts = repo.stale()
for alert in alerts:
    print(f"STALE: {alert.decision_label} (impact: {alert.impact_score:.0%})")

foghorn [--db PATH] COMMAND [OPTIONS]

# Stage facts
foghorn fact Redis is-appropriate-for rate-limiting
foghorn fact Postgres is-primary-db yes --confidence 0.9

# Stage a decision that depends on the Redis fact
foghorn decide chose-redis "Redis fits our rate-limiter requirements" \
    --on a3f8b2c1d4e5f6a7

# Commit
foghorn commit -m "Initial architecture decisions"

# Check for staleness (machine-readable)
foghorn stale --format json

# Fail CI if anything is stale
foghorn stale --exit-code

# .github/workflows/foghorn.yml
name: foghorn staleness check
on: [push, pull_request]

jobs:
  stale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: sandeep-alluru/foghorn@main
        with:
          db: .foghorn/world.db
          fail-on-stale: "true"

# Start the MCP server
python -m foghorn.mcp_server

# In your Claude Code project's .claude/settings.json:
{
  "mcpServers": {
    "foghorn": {
      "command": "python",
      "args": ["-m", "foghorn.mcp_server"]
    }
  }
}

# Start the REST server
uvicorn foghorn.api:app --reload

# Pass to Codex CLI or any OpenAI-compatible agent
codex --tools tools/openai-tools.json "Check which architecture decisions are stale"

foghorn/
├── src/
│   └── foghorn/
│       ├── fact.py           # Fact, Decision, StalenessAlert dataclasses
│       ├── store.py          # SQLite-backed WorldStore + WorldCommit
│       ├── staleness.py      # DiffResult, diff_commits(), compute_staleness()
│       ├── repo.py           # WorldRepo high-level API
│       ├── report.py         # print_stale(), print_diff(), to_json(), to_markdown()
│       ├── export.py         # export_json(), import_json(), export_graphviz()
│       ├── propagate.py      # propagate_staleness(), PropagationResult
│       ├── recommend.py      # recommend(), Recommendation
│       ├── cli.py            # Click CLI (fact, decide, commit, stale, diff, log, status, recommend)
│       ├── api.py            # FastAPI REST server
│       └── mcp_server.py     # MCP server (list_facts, record_decision, commit, check_stale)
├── tests/
│   ├── test_fact.py          # Fact, Decision, StalenessAlert unit tests
│   ├── test_store.py         # WorldStore + WorldCommit tests
│   ├── test_staleness.py     # Staleness propagation tests
│   ├── test_repo.py          # WorldRepo integration tests
│   └── test_cli.py           # CLI subprocess integration tests
├── examples/
│   └── demo.py               # Standalone demo script
├── docs/                     # MkDocs documentation
├── tools/
│   └── openai-tools.json     # OpenAI function-calling tool definitions
├── assets/
│   ├── hero.png              # README hero image
│   └── logo.png              # Project logo
├── action.yml                # GitHub Action
├── openapi.yaml              # OpenAPI 3.1 spec
├── pyproject.toml            # Package metadata + dependencies
└── CONTRIBUTING.md           # Contribution guide