[Request]: Shared Knowledge Vault for Agents (Obsidian-style Memory Across Tasks and Repos)

[stilero]

Problem or opportunity

Currently, each task in Ban Kan is executed in isolation.

While this is good for safety and reproducibility, it creates a major limitation:

• agents do not learn from previous tasks
• the same mistakes are repeated
• architectural decisions are rediscovered
• patterns are not reused consistently
• knowledge is lost between tasks and repos

Examples:

• an agent fixes a Stripe webhook issue → next task repeats the same mistake
• a project uses a specific validation pattern → future tasks ignore it
• architectural decisions (e.g. auth strategy) are not reused

This leads to:

• unnecessary retries
• inconsistent code
• slower execution
• increased token usage

There is an opportunity to introduce a persistent knowledge layer that allows agents to share learnings across tasks and repositories.

Proposed solution

Introduce a Shared Knowledge Vault (inspired by Obsidian) that acts as a persistent, structured memory layer for agents.

This vault allows:

• storing important learnings
• reusing patterns
• capturing architectural decisions
• avoiding repeated mistakes

---

1. Knowledge Vault structure

Create a local directory:

.bankan/knowledge/

Initial structure:

adr/        # architectural decisions
patterns/   # reusable implementation patterns
mistakes/   # known issues and fixes
repo/       # repo-specific notes
tasks/      # task-specific learnings (optional)

All entries are stored as Markdown files.

---

2. How agents read from the vault

During execution:

Planning phase

Planner agent reads:

• relevant ADRs
• repo notes
• patterns

Purpose:

• align with existing architecture
• avoid conflicting decisions
• reuse known approaches

---

Implementation phase

Implementation agent:

• checks patterns
• avoids known mistakes
• follows established conventions

---

Review phase

Reviewer agent:

• validates against ADRs
• flags violations of known patterns
• suggests improvements based on past learnings

---

3. Writing to the vault

Knowledge should be written selectively, not automatically.

After review:

• reviewer or supervisor decides if something is worth storing

Examples of what to store:

• architectural decisions (ADR)
• repeated mistakes and fixes
• reusable patterns
• important repo constraints

Examples of what NOT to store:

• temporary errors
• logs
• low-value noise

---

4. UI integration

Task details

Add a section:

Learnings from this task

Allow:

• manual save to vault
• auto-suggested entries (from reviewer/supervisor)

---

Knowledge view

Add a new tab:

Knowledge

Features:

• browse ADRs, patterns, mistakes
• search entries
• filter by repo or global

---

Task cards (optional)

Show:

• “uses knowledge” indicator
• number of references

---

5. Relevance system (future)

Initially, all knowledge can be loaded.

Later improvements:

• tag-based filtering
• repo-specific vs global knowledge
• semantic search
• auto-suggest relevant entries per task

Alternatives considered

1. No shared memory (current approach)

Each task runs independently.

Rejected because:

• agents repeat mistakes
• no learning over time
• inefficient workflows

---

2. Store memory per task only

Keep knowledge isolated to tasks.

Rejected because:

• no cross-task learning
• limited long-term value

---

3. Fully automatic memory logging

Store everything automatically.

Rejected because:

• creates noisy, low-quality knowledge
• difficult to maintain
• reduces trust in memory

---

4. External knowledge system (e.g. database)

Use external service instead of local files.

Rejected because:

• adds complexity
• breaks local-first principle
• harder to inspect and edit

Additional context

This feature introduces a new layer in Ban Kan:

• execution layer (agents)
• orchestration layer (kanban workflow)
• decision layer (supervisor agent)
• knowledge layer (shared memory)

Together, this moves Ban Kan toward:

• a self-improving AI development system
• long-term project intelligence
• consistent and predictable agent behavior

---

Suggested MVP scope

Start with:

• .bankan/knowledge/ folder
• basic structure (adr, patterns, mistakes)
• planner reads all knowledge files
• reviewer can write new entries (manual or assisted)
• simple UI list view

---

Success criteria

• agents avoid repeating known mistakes
• architectural consistency improves across tasks
• fewer retries required
• developers can inspect and trust stored knowledge
• knowledge compounds over time

---

Open questions

• Should knowledge be global or per repo (or both)?
• How to prevent outdated or conflicting knowledge?
• Should users approve all writes to the vault?
• How to surface “relevant knowledge” per task effectively?
• Should knowledge entries be versioned?

[m13v]

This is a well-thought-out proposal. The Obsidian-style markdown vault is a smart design choice because it is both human-readable and easy to version control.

One addition worth considering: semantic search over the vault entries. As the knowledge base grows past a few hundred entries, finding the right ADR or pattern by folder structure alone gets unreliable. We solved this by embedding each markdown file at save time and storing the vectors in sqlite-vec alongside the file metadata. Then at planning time, the agent embeds its task description and retrieves the top-K most relevant knowledge entries, rather than scanning everything.

This approach also helps with the cross-repo use case. You can maintain a global vault index that spans multiple repos and retrieve contextually relevant patterns regardless of which repo they came from.

For the mistakes/ directory specifically: attaching the error signature (stack trace hash or error message pattern) as metadata makes retrieval much more precise. When an agent encounters an error, it can search by the error fingerprint rather than relying purely on semantic similarity with the task description.

One gotcha with markdown-based knowledge: version the embedding model alongside the vault. If you swap models, all existing embeddings need re-computation, which is cheap but easy to forget.

[m13v]

Here is a reference for the embeddings + vector search layer that could work well for indexing the knowledge vault entries: https://github.com/m13v/ai-browser-profile/blob/main/ai_browser_profile/embeddings.py

And for the metadata storage + retrieval query patterns: https://github.com/m13v/ai-browser-profile/blob/main/ai_browser_profile/db.py

[stilero]

@m13v Thanks for the input, really valuable with new perspectives I didn't think of. Much appreciated 🙏