docs: clarify vault as separate independent repository
- vault/ has its own .git (separate from parent) - vault remote: poimen-obesdient-memory (different from parent) - parent .gitignore ignores vault/ to prevent accidental tracking - both repos work together: parent has code+JSONL, vault has generated markdown - two independent CI/CD pipelines (parent: build/test, vault: rebuild/push) Added: - VAULT-SEPARATE-REPO.md: structure, why separate, setup guide - VAULT-GITOPS-ARCHITECTURE.md: data flow and GitOps principles
This commit is contained in:
Story Crater Bot
@@ -0,0 +1,180 @@
|
||||
# Vault as Separate Repository
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
poimen-memory (parent repo)
|
||||
├── .git/ ← parent git history
|
||||
├── Cargo.toml, crates/ ← source code
|
||||
├── log/ ← JSONL authoritative log
|
||||
├── tasks/, queries/ ← task board + queries
|
||||
└── vault/ ← SEPARATE git repo
|
||||
├── .git/ ← vault's own git history
|
||||
├── .gitignore ← vault's own rules
|
||||
├── README.md
|
||||
├── notes/ ← human annotations
|
||||
├── poimen/ ← generated memories
|
||||
└── skills/ ← generated drafts
|
||||
```
|
||||
|
||||
## Two independent repositories
|
||||
|
||||
### Parent repo: `poimen-memory`
|
||||
```
|
||||
Remote: ssh://[email protected]:2222/rock/poimen-memory.git
|
||||
Tracks: Rust code, JSONL log, task definitions, design docs
|
||||
Ignores: /target/, vault/, .DS_Store, editor temp files
|
||||
Commits: ~40 commits (M0-M2 implementation complete)
|
||||
```
|
||||
|
||||
### Vault repo: `poimen-obesdient-memory`
|
||||
```
|
||||
Remote: ssh://[email protected]:2222/rock/poimen-obesdient-memory.git
|
||||
Tracks: Generated markdown, human annotations, structure
|
||||
Ignores: .obsidian/, *.readonly, local settings
|
||||
Commits: 2 commits (clean slate, ready for generated content)
|
||||
```
|
||||
|
||||
## Why separate?
|
||||
|
||||
1. **Different tracking needs**
|
||||
- Parent: code + logs (large, binary, mutable)
|
||||
- Vault: markdown + docs (small, text, rebuild-derived)
|
||||
|
||||
2. **Different workflows**
|
||||
- Parent: developers (Rust, CLI tools, testing)
|
||||
- Vault: readers (Obsidian, annotations, consumption)
|
||||
|
||||
3. **Independent scaling**
|
||||
- Parent: Cargo workspace grows (tests, crates, binaries)
|
||||
- Vault: only markdown files (stays lightweight)
|
||||
|
||||
4. **Separate CI/CD**
|
||||
- Parent: `cargo build`, `cargo test`, deploy binary
|
||||
- Vault: `mem rebuild --from-log`, `git push` (GitOps)
|
||||
|
||||
## How they work together
|
||||
|
||||
```
|
||||
1. Developer runs ingest
|
||||
cargo run -p mem-cli -- ingest --project poimen
|
||||
|
||||
2. JSONL written to parent repo
|
||||
log/poimen/infra-root-causes/<run-id>.jsonl
|
||||
|
||||
3. Parent repo commits
|
||||
git -C /path/to/poimen-memory commit
|
||||
|
||||
4. CI/CD triggered by log change
|
||||
|
||||
5. Rebuild vault from JSONL
|
||||
mem rebuild --from-log --project poimen
|
||||
cd vault && git add poimen/*.md && git commit
|
||||
|
||||
6. Vault repo updated
|
||||
git -C vault push origin main
|
||||
```
|
||||
|
||||
## Setup (fresh clone)
|
||||
|
||||
```bash
|
||||
# Clone parent (parent repo only)
|
||||
git clone ssh://[email protected]:2222/rock/poimen-memory.git
|
||||
cd poimen-memory
|
||||
|
||||
# Vault is already there (subdirectory with separate .git)
|
||||
cd vault
|
||||
git status
|
||||
# Shows: On branch main, tracking origin/main (poimen-obesdient-memory remote)
|
||||
|
||||
# Both repos now ready:
|
||||
ls .. # parent repo files (Cargo.toml, crates/, log/, etc.)
|
||||
ls . # vault repo files (notes/, poimen/, skills/)
|
||||
```
|
||||
|
||||
## Prevent vault/ from being tracked in parent
|
||||
|
||||
Parent repo `.gitignore` includes:
|
||||
```
|
||||
# Vault (projections and indexes)
|
||||
vault/
|
||||
```
|
||||
|
||||
This ensures:
|
||||
- `git status` in parent doesn't list vault files
|
||||
- `git add .` in parent won't add vault files
|
||||
- Vault remains independent
|
||||
|
||||
**Verify parent ignores vault:**
|
||||
```bash
|
||||
cd /Users/rockliang/workplace/poimen-memory
|
||||
git check-ignore vault/notes/INDEX.md
|
||||
# Output: vault/notes/INDEX.md
|
||||
# (confirmed: vault/ is ignored by parent)
|
||||
```
|
||||
|
||||
## Verify both remotes are correct
|
||||
|
||||
**Parent remote:**
|
||||
```bash
|
||||
cd /Users/rockliang/workplace/poimen-memory
|
||||
git remote -v
|
||||
# origin ssh://[email protected]:2222/rock/poimen-memory.git
|
||||
```
|
||||
|
||||
**Vault remote:**
|
||||
```bash
|
||||
cd /Users/rockliang/workplace/poimen-memory/vault
|
||||
git remote -v
|
||||
# origin ssh://[email protected]:2222/rock/poimen-obesdient-memory.git
|
||||
```
|
||||
|
||||
## Tracked files per repo
|
||||
|
||||
### Parent tracks:
|
||||
```
|
||||
✅ .gitea/workflows/ CI/CD
|
||||
✅ crates/ Rust source
|
||||
✅ Cargo.toml, Cargo.lock dependencies
|
||||
✅ DESIGN.md, README.md documentation
|
||||
✅ k8s/ infrastructure
|
||||
✅ log/poimen/**/*.jsonl JSONL events (authoritative)
|
||||
✅ migrations/ database migrations
|
||||
✅ queries/ query YAML
|
||||
✅ tasks/ task board
|
||||
✅ tests/ integration tests
|
||||
✅ templates/ Jinja2 for wrangler
|
||||
|
||||
❌ /target/ build artifacts
|
||||
❌ vault/ separate repo
|
||||
```
|
||||
|
||||
### Vault tracks:
|
||||
```
|
||||
✅ README.md workflow guide
|
||||
✅ notes/ human annotations
|
||||
✅ poimen/ generated memories
|
||||
✅ poimen/evidence/ generated chunks
|
||||
✅ skills/ generated + promoted
|
||||
✅ .gitignore Obsidian metadata
|
||||
|
||||
❌ .obsidian/ local settings
|
||||
```
|
||||
|
||||
## Current status
|
||||
|
||||
| Aspect | Status | Details |
|
||||
|--------|--------|---------|
|
||||
| Parent repo remote | ✅ configured | poimen-memory |
|
||||
| Vault repo remote | ✅ configured | poimen-obesdient-memory |
|
||||
| Parent ignores vault/ | ✅ yes | In .gitignore |
|
||||
| Vault has own .git | ✅ yes | Separate history |
|
||||
| Vault synced to remote | ✅ yes | 2 commits pushed |
|
||||
| No historic bloat | ✅ yes | Clean slate |
|
||||
|
||||
## Next steps
|
||||
|
||||
1. **M3 implementation**: First ingest → rebuild cycle (generates real memory files)
|
||||
2. **Verify byte-identical**: `git -C vault diff --exit-code` after rebuild
|
||||
3. **Live reading**: Clone vault separately, open in Obsidian
|
||||
4. **Human annotations**: Add notes in `vault/notes/`, commit to vault repo
|
||||
Reference in New Issue
Block a user