Philosophy
Core principles behind Knowns, based on the main GitHub repository philosophy document
Philosophy
This page summarizes the core philosophy from the Knowns repository.
Knowns is built around a simple idea: AI should understand your project the same way a teammate does.
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
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
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
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
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
Knowns treats AI like a teammate that should:
- read tasks
- read documentation
- follow references
- execute structured instructions consistently
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
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
If knowledge is explicit, structured, and versioned, AI can work like a real teammate.
Related
- Contributing - How to contribute within these principles
- Roadmap - Current direction from the main repository
- License - MIT license summary