pma-mem

Knowledge Palace

Capture and retrieve project knowledge. Storage backend: Memos ($MEMOS_URL, $MEMOS_TOKEN).

Always-On Rules

1. Confirm $MEMOS_URL and $MEMOS_TOKEN before any operation. If missing, ask the user.
2. Every knowledge entry must have a type tag.
3. Before writing, always check for duplicates by topicHash.
4. One memo = one knowledge point. Never bundle multiple topics into a single memo.
5. Related knowledge points must be linked via memo relations (REFERENCE).
6. Before implementing: query relevant knowledge first. Check for existing decisions, discoveries, and patterns that may apply to the current task.

When to Query

Agents should query the knowledge base in these situations:

• Hitting an error or unexpected behavior: query #discovery + keyword — someone may have seen this before
• Making a technical choice: query #decision + keyword — check if a decision was already made and why
• Implementing a pattern: query #pattern + keyword — reuse proven approaches
• Verifying an assumption: query #fact + keyword — confirm before building on it

Knowledge Types

5 types, flat tags, exactly one per memo:

#fact · #event · #discovery · #decision · #pattern

Additional tags are optional and free-form — agent decides based on content.

Full classification rules, content guidelines, and quality checks: see references/classification.md.

Memo Format

## {title}
 
{content — preserve context and reasoning, not just the conclusion}
 
#fact
 
<!-- {topicHash} from:{origin} -->

• Bottom comment is metadata: topicHash (dedup key, first 8 chars of md5(title)) + from: (knowledge origin, e.g. session, bkd/issueId, manual)
• Tags go in content body, not in metadata

Operations

Write

Query

Use queries to retrieve knowledge before acting. Return content to the agent context.

Capture

During a conversation, when the user says "remember this" / "save this" / "store this", or when the agent identifies knowledge worth preserving:

1. Extract one or more knowledge points from the current conversation
2. For each point, assign type + tags, generate topicHash
3. Dedup → create/update → link if multiple points

The agent should also proactively suggest capturing when it encounters:

• A non-obvious technical fact confirmed through debugging
• A decision made after weighing alternatives
• A gotcha or pitfall discovered during implementation
• A reusable pattern or workflow that worked well

Consolidate

On-demand: user asks to clean up or the agent notices overlapping memos during a query.

1. Load a tag group: curl -s -H "$AUTH" "$API/memos?filter=tag+in+[\"auth\"]&pageSize=100" | jq
2. Review for near-duplicates, superseded facts, or fragments
3. Merge into one memo, archive originals — see references/knowledge-sync.md for details

Reference Packs

• references/classification.md Type definitions, content guidelines, tagging rules, quality checks, consolidation rules.
• references/storage-api.md Memos REST API reference (CRUD, filters, relations, pagination, attachments).
• references/knowledge-sync.md Automated sync workflow: scanning, extraction, dedup, incremental update, automation guide.

Quick Routing

• Classifying or formatting knowledge: load references/classification.md.
• API details (updateMask, filters, error codes): load references/storage-api.md.
• Automated sync from task systems: load references/knowledge-sync.md.
• Simple capture or query: use operations above directly.