veclayer 0.1.0

Hierarchical vector memory for AI agents — perspectives, salience, aging, identity
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165

# VecLayer — Agent Conventions

## Identity & Attribution

Every agent interaction that produces a GitHub artifact (issue, comment, PR) **must** include attribution:

```
— <tool> - <model>
```

| Tool | When |
|------|------|
| `Claude Web - Opus 4.6` | Conversations in claude.ai web interface |
| `Claude Code - Opus 4.6` | Claude Code CLI sessions |
| `Claude Code - Sonnet 4.6` | Claude Code CLI with Sonnet model |
| `Claude Code - Haiku 4.5` | Claude Code CLI subagents using Haiku |
| `Opencode - Z.AI GLM-4.7` | Opencode CLI sessions |
| `OpenAI Codex - GPT-5` | OpenAI Codex sessions |
| `Florian Burka` | Human author |

This allows us to trace which model and tool produced each decision, design, or code change.
The list above is non-exhaustive: any agent/model should use `— <tool> - <model>` with their exact tool and model names.

## Code Quality

See [CODE_QUALITY.md](CODE_QUALITY.md) for full standards.

**The essentials:** 0 errors, 0 warnings, 0 test failures. Run `cargo fmt`, `cargo clippy`, `cargo nextest run` before every PR. Tests must assert real outcomes and fail on wrong results — "doesn't panic" is not a test. Cover green path, edge cases, and error path.

## Roadmap

The roadmap is tracked as GitHub Issues:

```bash
# View the full roadmap
gh issue list --label phase

# What's next?
gh issue list --label next

# What's done?
gh issue list --label done

# Open design questions
gh issue list --label open-question

# Discuss a roadmap item
gh issue comment <number> --body "..."
```

### Labels

| Label | Color | Purpose |
|-------|-------|---------|
| `phase` | green | Roadmap phase (1-7) |
| `done` | grey-green | Phase completed |
| `next` | red-orange | Next for implementation |
| `future` | light blue | Planned for later |
| `enhancement` | teal | Enhancement to existing phase |
| `open-question` | purple | Design question needing resolution |

### Rules

- One issue per phase, with a checklist of deliverables
- Enhancements and open questions get their own issues, linked to the parent phase
- Close phase issues only when all checklist items are done and verified
- Use comments for design discussion — keep the issue body as the source of truth
- Update issue body when decisions are made (don't let decisions get buried in comments)

## Memory Capture

- Use VecLayer perspectives to track decisions, learnings, and ongoing work
  - `decisions`: Architectural choices, configuration decisions
  - `learnings`: What worked/didn't, insights gained
  - `intentions`: Goals, upcoming work, ongoing threads
- Priming: Use `veclayer reflect` on session start (alias: `veclayer id`)
- Store significant moments automatically during work

## MCP Servers

- **veclayer**: Local hierarchical vector database for long-term memory
- **sonote.ai**: Remote MCP server for analysis and document storage (OAuth authenticated)

## Coordination

When multiple agents work on the same codebase:
- Check `gh issue list --label next` before starting work
- Comment on the issue you're working on to signal intent
- Reference issue numbers in commit messages (`fixes #N`, `ref #N`)
- Do not close issues without explicit human approval

## Agent Attribution

Commit messages should include attribution via `Co-Authored-By`:

```
<message body>

Co-Authored-By: <tool> - <model>
```

| Tool | Attribution |
|------|-------------|
| Claude Web - Opus 4.6 | `Co-Authored-By: Claude Web - Opus 4.6 <noreply@anthropic.com>` |
| Claude Code - Opus 4.6 | `Co-Authored-By: Claude Code - Opus 4.6 <noreply@anthropic.com>` |
| Claude Code - Sonnet 4.6 | `Co-Authored-By: Claude Code - Sonnet 4.6 <noreply@anthropic.com>` |
| Claude Code - Haiku 4.5 | `Co-Authored-By: Claude Code - Haiku 4.5 <noreply@anthropic.com>` |
| Opencode - Z.AI GLM-4.7 | `Co-Authored-By: Opencode - Z.AI GLM-4.7 <noreply@z.ai>` |
| OpenAI Codex - GPT-5 | `Co-Authored-By: OpenAI Codex - GPT-5 <noreply@openai.com>` |
| Florian Burka | Human author (no attribution line) |

For tools/models not listed above, use the same `Co-Authored-By: <tool> - <model> <noreply@provider>` pattern with the exact tool/model name.

## Pull Request Workflow

```bash
# 1. Create feature branch
git checkout -b feature-name

# 2. Work and commit
git add <files>
git commit -m "<type>: <description>"
# (include Co-Authored-By for attribution)

# 3. Push to remote
git push -u origin feature-name

# 4. Create PR with detailed description
gh pr create --title "feat: ..." --body "<detailed description>"
```

**PR Body Template:**
```markdown
## Summary
Brief description of what this PR does.

## Changes
- Change 1: description
- Change 2: description

## Test Coverage
- What was tested
- Test results

## Example Usage
\`\`\`bash
# CLI example
veclayer <command> ...

# MCP example
{...}
\`\`\`

Fixes #<issue-number>

— <tool> - <model>
```

**Commit Message Format:** `<type>: <description>`
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `refactor`: Code refactoring
- `test`: Tests only
- `chore`: Build/config changes