# Obsidian Knowledge Schema

## Goal

Use Obsidian as the human-maintained knowledge-of-record layer for developer memory.

The vault should be optimized for:

- retrieval quality
- durability
- provenance
- human editing
- AI consumption

## Recommended Directory Layout

```text
00-Identity/
  Developer Profile.md
  Collaboration Preferences.md
  Coding Style.md
  Decision Heuristics.md

10-Projects/
  <project-id>/
    Project Overview.md
    Architecture.md
    Domain Model.md
    Constraints.md
    Runbook.md
    Known Pitfalls.md
    Glossary.md
    Memory Map.md

11-Decisions/
  ADR-0001-*.md
  ADR-0002-*.md

12-Incidents/
  Incident-*.md
  Postmortem-*.md

20-Patterns/
  Language/
  Framework/
  Security/
  Tooling/

30-Workflows/
  Debugging Workflow.md
  Release Workflow.md
  Review Workflow.md

40-People/
  Team Preferences.md
  Stakeholder Map.md

50-Memory-Ledger/
  Session/
  Daily/
  Weekly/
  Extracted/
```

## Required Frontmatter Fields

Every retrieval-oriented note should define:

```yaml
memory_type: project
project_id: spool
scope: personal
sensitivity: internal
freshness: evergreen
source_of_truth: true
retrieval_priority: high
triggers:
  - routing
  - repo_path
related_files:
  - src/engine/scorer.rs
related_memory:
  - ADR-0001
review_after: 2026-06-01
```

## Field Semantics

### `memory_type`

Allowed initial values:

- `project`
- `decision`
- `preference`
- `constraint`
- `pattern`
- `incident`
- `person`
- `workflow`
- `session`

### `project_id`

Used for strict project routing. This should match `projects.id` in `spool` config.

### `scope`

Suggested values:

- `personal`
- `project`
- `team`
- `org`

### `sensitivity`

Suggested values:

- `public`
- `internal`
- `confidential`
- `secret`

Current retrieval behavior:

- `internal` is neutral
- `public` gets a small boost
- `confidential` gets a small deboost
- `secret` gets a stronger deboost until a proper policy engine exists

### `freshness`

Suggested values:

- `evergreen`
- `active`
- `stale`

### `source_of_truth`

Marks whether a note should be preferred over derivative memory summaries.

Current retrieval behavior:

- `true` gives a ranking boost

### `retrieval_priority`

Suggested values:

- `high`
- `medium`
- `low`

This should influence ranking before generic lexical matches.

Current retrieval behavior:

- `high` boosts ranking
- `medium` gives a smaller boost
- `low` slightly deboosts ranking

### `triggers`

Explicit retrieval keywords for routing beyond raw body text.

### `related_files`

Important for file-aware retrieval.

### `related_memory`

Used to connect decisions, incidents, and workflows.

### `review_after`

Supports stale-memory review and pruning.

## Note-Type Guidance

### Project Notes

Should explain stable project facts:

- purpose
- architecture
- invariants
- constraints
- operational knowledge

### Decision Notes

Should record:

- context
- options considered
- chosen path
- reason
- reversal conditions

### Incident Notes

Should record:

- symptom
- blast radius
- root cause
- fix
- prevention

### Preference Notes

Should record durable developer or team preferences:

- review style
- coding style
- debugging style
- communication preferences

## Authoring Rules

1. one note should represent one durable memory object
2. titles should be explicit and query-friendly
3. headings should mirror retrieval-friendly subtopics
4. important files should be listed in `related_files`
5. major decisions should always backlink to projects and incidents

## AI-Specific Guidance

Do not optimize Obsidian notes only for human reading or only for model ingestion.

Each important note should have:

- a clear title
- explicit headings
- frontmatter metadata
- short direct statements
- links to source notes or ADRs

## Integration With Automatic Memory

The `50-Memory-Ledger/` tree should hold machine-assisted intermediate artifacts, not authoritative long-term truth by default.

Promotion rule:

Raw session memory should be promoted into `10-Projects`, `11-Decisions`, `12-Incidents`, or `30-Workflows` only after review or confidence checks.
