# Philosophy

Core principles behind Knowns, based on the main GitHub repository philosophy document

# [Philosophy](https://knowns.sh/docs/philosophy#philosophy)

This page summarizes the core philosophy from the [Knowns repository](https://github.com/knowns-dev/knowns).

Knowns is built around a simple idea: **AI should understand your project the same way a teammate does.**

## [AI Should Read, Not Guess](https://knowns.sh/docs/philosophy#ai-should-read-not-guess)

Knowns is designed so AI reads real project artifacts instead of depending on prompt tricks or repeated explanations.

That means:

- context should be explicit, structured, and versioned
- important knowledge should not live only in chat history
- references should resolve back to real project files

## [Files Are The Source Of Truth](https://knowns.sh/docs/philosophy#files-are-the-source-of-truth)

Knowns is file-first and local-first.

- tasks are files
- docs are files
- structure lives on disk
- project knowledge stays versionable in Git

This avoids hidden state and keeps knowledge portable.

## [Explicit Context Beats Memory](https://knowns.sh/docs/philosophy#explicit-context-beats-memory)

Knowns favors resolvable references such as `@doc/...` and `@task-...` over fuzzy memory.

The goal is deterministic context loading instead of guesswork.

## [Local-First, Sync Optional](https://knowns.sh/docs/philosophy#local-first-sync-optional)

The local project remains the source of truth.

If teams use sync or shared visibility features later, those layers should not replace local files.

## [CLI First](https://knowns.sh/docs/philosophy#cli-first)

Knowns is built for developers who need a scriptable, composable, automation-friendly interface.

The Web UI exists to visualize and browse, not to replace the CLI.

## [AI As Teammate](https://knowns.sh/docs/philosophy#ai-as-teammate)

Knowns treats AI like a teammate that should:

- read tasks
- read documentation
- follow references
- execute structured instructions consistently

## [Keep The Model Simple](https://knowns.sh/docs/philosophy#keep-the-model-simple)

Knowns intentionally centers a few primitives:

- tasks
- documents
- references
- files

This keeps the system easier to reason about and harder to break.

## [What Knowns Is Not](https://knowns.sh/docs/philosophy#what-knowns-is-not)

To stay focused, Knowns avoids becoming:

- a full project management suite
- a ticketing platform
- a SaaS dashboard
- a replacement for Git
- a generic note-taking app

## [Core Belief](https://knowns.sh/docs/philosophy#core-belief)

> If knowledge is explicit, structured, and versioned, AI can work like a real teammate.