Skip to content

Commit c514fa4

Browse files
codeaholicguycodeaholicguy
committed
Add memory skill
1 parent 59e105e commit c514fa4

3 files changed

Lines changed: 255 additions & 5 deletions

File tree

‎packages/cli/templates/env/base.md‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,26 @@ This project uses ai-devkit for structured AI-assisted development. Phase docume
2828
- For new features, start with requirements clarification
2929
- Update phase docs when significant changes or decisions are made
3030

31+
## Skills (Extend Your Capabilities)
32+
Skills are packaged capabilities that teach you new competencies, patterns, and best practices. Check for installed skills in the project's skill directory and use them to enhance your work.
33+
34+
### Using Installed Skills
35+
1. **Check for skills**: Look for `SKILL.md` files in the project's skill directory
36+
2. **Read skill instructions**: Each skill contains detailed guidance on when and how to use it
37+
3. **Apply skill knowledge**: Follow the patterns, commands, and best practices defined in the skill
38+
39+
### Key Installed Skills
40+
- **memory**: Use AI DevKit's memory service via CLI commands when MCP is unavailable. Read the skill for detailed `memory store` and `memory search` command usage.
41+
42+
### When to Reference Skills
43+
- Before implementing features that match a skill's domain
44+
- When MCP tools are unavailable but skill provides CLI alternatives
45+
- To follow established patterns and conventions defined in skills
46+
3147
## Knowledge Memory (Always Use When Helpful)
32-
The AI assistant should proactively use knowledge memory throughout all interactions:
48+
The AI assistant should proactively use knowledge memory throughout all interactions.
49+
50+
> **Tip**: If MCP is unavailable, use the **memory skill** for detailed CLI command reference.
3351
3452
### When to Search Memory
3553
- Before starting any task, search for relevant project conventions, patterns, or decisions
@@ -39,7 +57,7 @@ The AI assistant should proactively use knowledge memory throughout all interact
3957

4058
**How to search**:
4159
- Use `memory.searchKnowledge` MCP tool with relevant keywords, tags, and scope
42-
- If MCP tools are unavailable, use `npx ai-devkit memory search` CLI command
60+
- If MCP tools are unavailable, use `npx ai-devkit memory search` CLI command (see memory skill for details)
4361
- Example: Search for "authentication patterns" when implementing auth features
4462

4563
### When to Store Memory
@@ -50,7 +68,7 @@ The AI assistant should proactively use knowledge memory throughout all interact
5068

5169
**How to store**:
5270
- Use `memory.storeKnowledge` MCP tool
53-
- If MCP tools are unavailable, use `npx ai-devkit memory store` CLI command
71+
- If MCP tools are unavailable, use `npx ai-devkit memory store` CLI command (see memory skill for details)
5472
- Include clear title, detailed content, relevant tags, and appropriate scope
5573
- Make knowledge specific and actionable, not generic advice
5674

‎skills/memory/SKILL.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
---
2+
name: memory
3+
description: Use AI DevKit's memory service to store and retrieve knowledge via CLI commands instead of MCP.
4+
---
5+
6+
# AI DevKit Memory Skill
7+
8+
This skill teaches you how to use AI DevKit's **Memory** service through CLI commands. Memory allows you to store actionable insights, coding patterns, and project guidelines that persist across sessions.
9+
10+
## When to Use This Skill
11+
12+
Use the memory CLI commands when:
13+
- MCP (Model Context Protocol) is not available or not configured
14+
- You need to store knowledge directly from the terminal
15+
- You want to search for previously stored patterns or guidelines
16+
- You're scripting memory operations
17+
18+
## Prerequisites
19+
20+
Ensure AI DevKit CLI is available:
21+
```bash
22+
npx ai-devkit --version
23+
```
24+
25+
## Commands Reference
26+
27+
### Storing Knowledge
28+
29+
Store new knowledge items using the `memory store` command:
30+
31+
```bash
32+
npx ai-devkit memory store \
33+
--title "<short descriptive title>" \
34+
--content "<detailed knowledge content>" \
35+
--tags "<comma-separated tags>" \
36+
--scope "<scope>"
37+
```
38+
39+
**Parameters:**
40+
41+
| Parameter | Required | Description |
42+
|-------------|----------|-------------|
43+
| `--title` | Yes | Short, descriptive title (5-12 words, 10-100 chars) |
44+
| `--content` | Yes | Detailed explanation in markdown format (50-5000 chars) |
45+
| `--tags` | No | Comma-separated domain keywords (e.g., `typescript,react`) |
46+
| `--scope` | No | `global` (default), `project:<name>`, or `repo:<org/repo>` |
47+
48+
**Examples:**
49+
50+
```bash
51+
# Store a global coding pattern
52+
npx ai-devkit memory store \
53+
--title "Always handle BigInt serialization in API responses" \
54+
--content "When returning BigInt values from API endpoints, convert them to strings using \`BigInt.toString()\` before serialization. JSON.stringify() cannot serialize BigInt natively." \
55+
--tags "api,backend,serialization" \
56+
--scope "global"
57+
58+
# Store project-specific knowledge
59+
npx ai-devkit memory store \
60+
--title "Use pnpm for package management" \
61+
--content "This monorepo uses pnpm workspaces. Always use 'pnpm' instead of 'npm' or 'yarn'. Install dependencies with 'pnpm install' and run scripts with 'pnpm run <script>'." \
62+
--scope "project:my-monorepo"
63+
64+
# Store repository-specific rules
65+
npx ai-devkit memory store \
66+
--title "Database migrations require review" \
67+
--content "All database schema changes must be reviewed by the DBA team before merging. Create migration files in /migrations and tag the PR with 'needs-dba-review'." \
68+
--tags "database,migrations,process" \
69+
--scope "repo:myorg/backend-api"
70+
```
71+
72+
### Searching Knowledge
73+
74+
Search for stored knowledge using the `memory search` command:
75+
76+
```bash
77+
npx ai-devkit memory search --query "<search query>"
78+
```
79+
80+
**Parameters:**
81+
82+
| Parameter | Required | Description |
83+
|-----------|----------|-------------|
84+
| `--query` | Yes | Natural language search query (3-500 chars) |
85+
| `--tags` | No | Comma-separated tags to boost matching (e.g., `api,backend`) |
86+
| `--scope` | No | Filter by scope (results from matching scope are prioritized) |
87+
| `--limit` | No | Maximum results to return (1-20, default: 5) |
88+
89+
**Example:**
90+
91+
```bash
92+
# Basic search
93+
npx ai-devkit memory search --query "API response handling"
94+
95+
# Search with tag boosting
96+
npx ai-devkit memory search \
97+
--query "docker configuration" \
98+
--tags "docker,infra"
99+
100+
# Search within a specific scope
101+
npx ai-devkit memory search \
102+
--query "coding standards" \
103+
--scope "project:my-app" \
104+
--limit 10
105+
```
106+
107+
**Output Format:**
108+
109+
The search command returns JSON with ranked results:
110+
111+
```json
112+
{
113+
"results": [
114+
{
115+
"id": "uuid-string",
116+
"title": "Knowledge title",
117+
"content": "Detailed content...",
118+
"tags": ["tag1", "tag2"],
119+
"scope": "global",
120+
"score": 5.2
121+
}
122+
],
123+
"totalMatches": 1,
124+
"query": "your search query"
125+
}
126+
```
127+
128+
## Best Practices
129+
130+
### Crafting Good Titles
131+
- Be explicit and actionable: "Always validate user input before database queries"
132+
- Include the domain: "React: Use useCallback for event handlers in list items"
133+
- Keep it concise: 5-12 words that capture the essence
134+
135+
### Writing Effective Content
136+
- Use markdown for formatting
137+
- Include code examples when applicable
138+
- Explain the "why" not just the "what"
139+
- Add edge cases and exceptions
140+
141+
### Using Tags Effectively
142+
- Use lowercase, single-word tags
143+
- Include technology names: `typescript`, `react`, `docker`
144+
- Include domains: `api`, `frontend`, `testing`, `security`
145+
- Include action types: `debugging`, `performance`, `patterns`
146+
147+
### Choosing the Right Scope
148+
149+
| Scope | Use When |
150+
|-------|----------|
151+
| `global` | Knowledge applies to all your projects |
152+
| `project:<name>` | Specific to a named project |
153+
| `repo:<org/repo>` | Specific to a git repository |
154+
155+
## Integration with AI Workflows
156+
157+
When storing knowledge during a conversation:
158+
159+
1. **Before storing**, search to avoid duplicates:
160+
```bash
161+
npx ai-devkit memory search --query "similar topic"
162+
```
163+
164+
2. **After resolving an issue**, store the solution:
165+
```bash
166+
npx ai-devkit memory store \
167+
--title "Fix: Issue description" \
168+
--content "Solution details with code examples..." \
169+
--tags "relevant,tags"
170+
```
171+
172+
3. **Before starting a task**, search for relevant context:
173+
```bash
174+
npx ai-devkit memory search --query "task description"
175+
```
176+
177+
## Storage Location
178+
179+
All memory data is stored locally at:
180+
```
181+
~/.ai-devkit/memory.db
182+
```
183+
184+
This SQLite database is portable—copy it to another machine to share knowledge.
185+
186+
## Troubleshooting
187+
188+
### "Duplicate title" error
189+
A knowledge item with a similar title already exists in that scope. Either:
190+
- Use a more specific title
191+
- Update the existing entry (delete and re-add)
192+
- Use a different scope
193+
194+
### "Query too short" error
195+
Search queries must be at least 3 characters. Provide more context in your search.
196+
197+
### Empty search results
198+
- Broaden your search terms
199+
- Remove tag filters
200+
- Try different keyword variations

‎web/content/docs/6-memory.md‎

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,11 @@ Before using Memory, ensure you have:
1919

2020
## How It Works
2121

22-
You can interact with Memory in two ways:
22+
You can interact with Memory in three ways:
2323

24-
1. **Through your AI Assistant (Recommended):** Connect via MCP so your AI can automatically search for relevant context and save new rules as you work. When you chat with your AI assistant, it will automatically fallback to the CLI to search for relevant context and save new rules if MCP is not available.
24+
1. **Through your AI Assistant (Recommended):** Connect via MCP so your AI can automatically search for relevant context and save new rules as you work.
2525
2. **Through the CLI:** Manually store or retrieve knowledge directly from your terminal—perfect for quick lookups or scripting.
26+
3. **Through Skills:** Install the memory skill to teach your AI agent how to use CLI commands when MCP is unavailable.
2627

2728
## Using with AI Agents (MCP)
2829

@@ -110,6 +111,37 @@ ai-devkit memory search --query "docker m1"
110111

111112
> **Note:** If no results are found, an empty array `[]` is returned.
112113
114+
## Using the Memory Skill
115+
116+
If MCP is not available in your environment, you can install the **memory skill** to teach your AI agent how to use memory via CLI commands.
117+
118+
### Installing the Skill
119+
120+
```bash
121+
ai-devkit skill add codeaholicguy/ai-devkit memory
122+
```
123+
124+
This installs the memory skill into your project's skill directory (e.g., `.cursor/skills/memory/`).
125+
126+
### What the Skill Provides
127+
128+
Once installed, your AI agent will have access to:
129+
130+
- **Detailed CLI command reference** for `memory store` and `memory search`
131+
- **Parameter documentation** with examples for all options
132+
- **Best practices** for crafting titles, content, and tags
133+
- **Troubleshooting tips** for common issues
134+
135+
### When to Use the Skill
136+
137+
The memory skill is ideal when:
138+
139+
- MCP is not configured or unavailable
140+
- Your AI agent needs detailed command syntax reference
141+
- You want consistent memory usage patterns across your team
142+
143+
> **Tip:** The skill works with all skill-capable AI environments: Cursor, Claude Code, Codex, OpenCode, and Antigravity.
144+
113145
## Organizing Your Knowledge
114146

115147
To keep your memory effective, use **Tags** and **Scopes**.

0 commit comments

Comments
 (0)