basic-memory 0.15.0__py3-none-any.whl → 0.15.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of basic-memory might be problematic. Click here for more details.
- basic_memory/__init__.py +1 -1
- basic_memory/api/routers/directory_router.py +23 -2
- basic_memory/api/routers/project_router.py +1 -0
- basic_memory/cli/auth.py +2 -2
- basic_memory/cli/commands/command_utils.py +11 -28
- basic_memory/cli/commands/mcp.py +72 -67
- basic_memory/cli/commands/project.py +54 -49
- basic_memory/cli/commands/status.py +6 -15
- basic_memory/config.py +55 -9
- basic_memory/deps.py +7 -5
- basic_memory/ignore_utils.py +7 -7
- basic_memory/mcp/async_client.py +102 -4
- basic_memory/mcp/prompts/continue_conversation.py +16 -15
- basic_memory/mcp/prompts/search.py +12 -11
- basic_memory/mcp/resources/ai_assistant_guide.md +185 -453
- basic_memory/mcp/resources/project_info.py +9 -7
- basic_memory/mcp/tools/build_context.py +40 -39
- basic_memory/mcp/tools/canvas.py +21 -20
- basic_memory/mcp/tools/chatgpt_tools.py +11 -2
- basic_memory/mcp/tools/delete_note.py +22 -21
- basic_memory/mcp/tools/edit_note.py +105 -104
- basic_memory/mcp/tools/list_directory.py +98 -95
- basic_memory/mcp/tools/move_note.py +127 -125
- basic_memory/mcp/tools/project_management.py +101 -98
- basic_memory/mcp/tools/read_content.py +64 -63
- basic_memory/mcp/tools/read_note.py +88 -88
- basic_memory/mcp/tools/recent_activity.py +139 -135
- basic_memory/mcp/tools/search.py +27 -26
- basic_memory/mcp/tools/sync_status.py +133 -128
- basic_memory/mcp/tools/utils.py +0 -15
- basic_memory/mcp/tools/view_note.py +14 -28
- basic_memory/mcp/tools/write_note.py +97 -87
- basic_memory/repository/entity_repository.py +60 -0
- basic_memory/repository/repository.py +16 -3
- basic_memory/repository/search_repository.py +42 -0
- basic_memory/schemas/project_info.py +1 -1
- basic_memory/services/directory_service.py +124 -3
- basic_memory/services/entity_service.py +31 -9
- basic_memory/services/project_service.py +97 -10
- basic_memory/services/search_service.py +16 -8
- basic_memory/sync/sync_service.py +28 -13
- {basic_memory-0.15.0.dist-info → basic_memory-0.15.1.dist-info}/METADATA +51 -4
- {basic_memory-0.15.0.dist-info → basic_memory-0.15.1.dist-info}/RECORD +46 -47
- basic_memory/mcp/tools/headers.py +0 -44
- {basic_memory-0.15.0.dist-info → basic_memory-0.15.1.dist-info}/WHEEL +0 -0
- {basic_memory-0.15.0.dist-info → basic_memory-0.15.1.dist-info}/entry_points.txt +0 -0
- {basic_memory-0.15.0.dist-info → basic_memory-0.15.1.dist-info}/licenses/LICENSE +0 -0
|
@@ -1,551 +1,283 @@
|
|
|
1
1
|
# AI Assistant Guide for Basic Memory
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
navigating knowledge through the Model Context Protocol (MCP).
|
|
3
|
+
Quick reference for using Basic Memory tools effectively through MCP.
|
|
5
4
|
|
|
6
|
-
|
|
5
|
+
**For comprehensive coverage**: See the [Extended AI Assistant Guide](https://github.com/basicmachines-co/basic-memory/blob/main/docs/ai-assistant-guide-extended.md) with detailed examples, advanced patterns, and self-contained sections.
|
|
7
6
|
|
|
8
|
-
|
|
9
|
-
natural conversations. The system automatically creates a semantic knowledge graph from simple text patterns.
|
|
7
|
+
## Overview
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
- **Real-Time**: Users see content updates immediately
|
|
13
|
-
- **Bi-Directional**: Both you and users can read and edit notes
|
|
14
|
-
- **Semantic**: Simple patterns create a structured knowledge graph
|
|
15
|
-
- **Persistent**: Knowledge persists across sessions and conversations
|
|
9
|
+
Basic Memory creates a semantic knowledge graph from markdown files. Focus on building rich connections between notes.
|
|
16
10
|
|
|
17
|
-
|
|
11
|
+
- **Local-First**: Plain text files on user's computer
|
|
12
|
+
- **Persistent**: Knowledge survives across sessions
|
|
13
|
+
- **Semantic**: Observations and relations create a knowledge graph
|
|
18
14
|
|
|
19
|
-
|
|
15
|
+
**Your role**: You're helping humans build enduring knowledge they'll own forever. The semantic graph (observations, relations, context) helps you provide better assistance by understanding connections and maintaining continuity. Think: lasting insights worth keeping, not disposable chat logs.
|
|
20
16
|
|
|
21
|
-
|
|
17
|
+
## Project Management
|
|
22
18
|
|
|
23
|
-
|
|
24
|
-
2. **Explicit Project Parameter (Medium Priority)**: When you specify `project="project-name"` in tool calls
|
|
25
|
-
3. **Default Project Mode (Lowest Priority)**: When `default_project_mode=true` in configuration, tools automatically use the configured `default_project`
|
|
19
|
+
All tools require explicit project specification.
|
|
26
20
|
|
|
27
|
-
|
|
21
|
+
**Three-tier resolution:**
|
|
22
|
+
1. CLI constraint: `--project name` (highest priority)
|
|
23
|
+
2. Explicit parameter: `project="name"` in tool calls
|
|
24
|
+
3. Default mode: `default_project_mode=true` in config (fallback)
|
|
28
25
|
|
|
29
|
-
|
|
30
|
-
- All tools become more convenient - no need to specify project repeatedly
|
|
31
|
-
- Perfect for users who primarily work with a single project
|
|
32
|
-
- Still allows explicit project specification when needed
|
|
33
|
-
- Falls back gracefully to multi-project mode if no default is configured
|
|
26
|
+
### Quick Setup Check
|
|
34
27
|
|
|
35
28
|
```python
|
|
36
|
-
#
|
|
37
|
-
await
|
|
38
|
-
await write_note("My Note", "Content", "folder", project="default-project")
|
|
29
|
+
# Discover projects
|
|
30
|
+
projects = await list_memory_projects()
|
|
39
31
|
|
|
40
|
-
#
|
|
41
|
-
|
|
32
|
+
# Check if default_project_mode enabled
|
|
33
|
+
# If yes: project parameter optional
|
|
34
|
+
# If no: project parameter required
|
|
42
35
|
```
|
|
43
36
|
|
|
44
|
-
### Project
|
|
37
|
+
### Default Project Mode
|
|
45
38
|
|
|
46
|
-
|
|
39
|
+
When `default_project_mode=true`:
|
|
47
40
|
```python
|
|
48
|
-
#
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
# See recent activity across projects for recommendations
|
|
52
|
-
activity = await recent_activity() # Shows cross-project activity and suggestions
|
|
41
|
+
# These are equivalent:
|
|
42
|
+
await write_note("Note", "Content", "folder")
|
|
43
|
+
await write_note("Note", "Content", "folder", project="main")
|
|
53
44
|
```
|
|
54
45
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
**Basic Memory's value comes from connections between notes, not just the notes themselves.**
|
|
58
|
-
|
|
59
|
-
When writing notes, your primary goal should be creating a rich, interconnected knowledge graph:
|
|
60
|
-
|
|
61
|
-
1. **Increase Semantic Density**: Add multiple observations and relations to each note
|
|
62
|
-
2. **Use Accurate References**: Aim to reference existing entities by their exact titles
|
|
63
|
-
3. **Create Forward References**: Feel free to reference entities that don't exist yet - Basic Memory will resolve these
|
|
64
|
-
when they're created later
|
|
65
|
-
4. **Create Bidirectional Links**: When appropriate, connect entities from both directions
|
|
66
|
-
5. **Use Meaningful Categories**: Add semantic context with appropriate observation categories
|
|
67
|
-
6. **Choose Precise Relations**: Use specific relation types that convey meaning
|
|
68
|
-
|
|
69
|
-
Remember: A knowledge graph with 10 heavily connected notes is more valuable than 20 isolated notes. Your job is to help
|
|
70
|
-
build these connections!
|
|
71
|
-
|
|
72
|
-
## Core Tools Reference
|
|
73
|
-
|
|
74
|
-
### Knowledge Creation and Editing
|
|
75
|
-
|
|
46
|
+
When `default_project_mode=false` (default):
|
|
76
47
|
```python
|
|
77
|
-
#
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
folder="specs", # Required: Folder to save in
|
|
82
|
-
tags=["search", "design"], # Optional: Tags for categorization
|
|
83
|
-
project="my-project" # Optional: Explicit project (uses default if not specified)
|
|
84
|
-
)
|
|
48
|
+
# Project required:
|
|
49
|
+
await write_note("Note", "Content", "folder", project="main") # ✓
|
|
50
|
+
await write_note("Note", "Content", "folder") # ✗ Error
|
|
51
|
+
```
|
|
85
52
|
|
|
86
|
-
|
|
87
|
-
await edit_note(
|
|
88
|
-
identifier="Search Design", # Required: Note to edit
|
|
89
|
-
operation="append", # Required: append, prepend, find_replace, replace_section
|
|
90
|
-
content="\n## New Section\nAdditional content", # Required: Content to add/replace
|
|
91
|
-
project="my-project" # Optional: Explicit project
|
|
92
|
-
)
|
|
53
|
+
## Core Tools
|
|
93
54
|
|
|
94
|
-
|
|
95
|
-
await move_note(
|
|
96
|
-
identifier="Search Design", # Required: Note to move
|
|
97
|
-
destination_path="archive/old-search-design.md", # Required: New location
|
|
98
|
-
project="my-project" # Optional: Explicit project
|
|
99
|
-
)
|
|
55
|
+
### Writing Knowledge
|
|
100
56
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
57
|
+
```python
|
|
58
|
+
await write_note(
|
|
59
|
+
title="Topic",
|
|
60
|
+
content="# Topic\n## Observations\n- [category] fact\n## Relations\n- relates_to [[Other]]",
|
|
61
|
+
folder="notes",
|
|
62
|
+
project="main" # Required unless default_project_mode=true
|
|
105
63
|
)
|
|
106
64
|
```
|
|
107
65
|
|
|
108
|
-
###
|
|
66
|
+
### Reading Knowledge
|
|
109
67
|
|
|
110
68
|
```python
|
|
111
|
-
#
|
|
112
|
-
content = await read_note("
|
|
113
|
-
content = await read_note("specs/search-design") # By path
|
|
114
|
-
content = await read_note("memory://specs/search") # By memory URL
|
|
115
|
-
content = await read_note("Search Design", project="work-docs") # Explicit project
|
|
116
|
-
|
|
117
|
-
# Reading raw file content (text, images, binaries)
|
|
118
|
-
file_data = await read_content(
|
|
119
|
-
path="assets/diagram.png", # Required: File path
|
|
120
|
-
project="my-project" # Optional: Explicit project
|
|
121
|
-
)
|
|
122
|
-
|
|
123
|
-
# Viewing notes as formatted artifacts
|
|
124
|
-
await view_note(
|
|
125
|
-
identifier="Search Design", # Required: Note to view
|
|
126
|
-
project="my-project", # Optional: Explicit project
|
|
127
|
-
page=1, # Optional: Pagination
|
|
128
|
-
page_size=10 # Optional: Items per page
|
|
129
|
-
)
|
|
69
|
+
# By identifier
|
|
70
|
+
content = await read_note("Topic", project="main")
|
|
130
71
|
|
|
131
|
-
#
|
|
132
|
-
|
|
133
|
-
dir_name="/specs", # Optional: Directory path (default: "/")
|
|
134
|
-
depth=2, # Optional: Recursion depth
|
|
135
|
-
file_name_glob="*.md", # Optional: File pattern filter
|
|
136
|
-
project="my-project" # Optional: Explicit project
|
|
137
|
-
)
|
|
72
|
+
# By memory:// URL
|
|
73
|
+
content = await read_note("memory://folder/topic", project="main")
|
|
138
74
|
```
|
|
139
75
|
|
|
140
|
-
###
|
|
76
|
+
### Searching
|
|
141
77
|
|
|
142
78
|
```python
|
|
143
|
-
# Searching for knowledge
|
|
144
79
|
results = await search_notes(
|
|
145
|
-
query="authentication
|
|
146
|
-
project="
|
|
147
|
-
|
|
148
|
-
page_size=10, # Optional: Results per page
|
|
149
|
-
search_type="text", # Optional: "text", "title", or "permalink"
|
|
150
|
-
types=["entity"], # Optional: Filter by content types
|
|
151
|
-
entity_types=["observation"], # Optional: Filter by entity types
|
|
152
|
-
after_date="1 week" # Optional: Recent content only
|
|
153
|
-
)
|
|
154
|
-
|
|
155
|
-
# Building context from the knowledge graph
|
|
156
|
-
context = await build_context(
|
|
157
|
-
url="memory://specs/search", # Required: Starting point
|
|
158
|
-
project="my-project", # Optional: Explicit project
|
|
159
|
-
depth=2, # Optional: How many hops to follow
|
|
160
|
-
timeframe="1 month", # Optional: Recent timeframe
|
|
161
|
-
max_related=10 # Optional: Max related items
|
|
162
|
-
)
|
|
163
|
-
|
|
164
|
-
# Checking recent changes
|
|
165
|
-
activity = await recent_activity(
|
|
166
|
-
type=["entity", "relation"], # Optional: Entity types to include
|
|
167
|
-
depth=1, # Optional: Related items to include
|
|
168
|
-
timeframe="1 week", # Optional: Time window
|
|
169
|
-
project="my-project" # Optional: Explicit project (None for cross-project discovery)
|
|
80
|
+
query="authentication",
|
|
81
|
+
project="main",
|
|
82
|
+
page_size=10
|
|
170
83
|
)
|
|
171
84
|
```
|
|
172
85
|
|
|
173
|
-
###
|
|
86
|
+
### Building Context
|
|
174
87
|
|
|
175
88
|
```python
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
folder="diagrams", # Required: Storage location
|
|
182
|
-
project="my-project" # Optional: Explicit project
|
|
89
|
+
context = await build_context(
|
|
90
|
+
url="memory://specs/auth",
|
|
91
|
+
project="main",
|
|
92
|
+
depth=2,
|
|
93
|
+
timeframe="1 week"
|
|
183
94
|
)
|
|
184
|
-
|
|
185
|
-
# Project management
|
|
186
|
-
projects = await list_memory_projects() # List all available projects
|
|
187
|
-
project_info = await project_info(project="my-project") # Get project statistics
|
|
188
95
|
```
|
|
189
96
|
|
|
190
|
-
##
|
|
191
|
-
|
|
192
|
-
Basic Memory uses a special URL format to reference entities in the knowledge graph:
|
|
193
|
-
|
|
194
|
-
- `memory://title` - Reference by title
|
|
195
|
-
- `memory://folder/title` - Reference by folder and title
|
|
196
|
-
- `memory://permalink` - Reference by permalink
|
|
197
|
-
- `memory://path/relation_type/*` - Follow all relations of a specific type
|
|
198
|
-
- `memory://path/*/target` - Find all entities with relations to target
|
|
97
|
+
## Knowledge Graph Essentials
|
|
199
98
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
Knowledge is encoded in standard markdown using simple patterns:
|
|
203
|
-
|
|
204
|
-
**Observations** - Facts about an entity:
|
|
99
|
+
### Observations
|
|
205
100
|
|
|
101
|
+
Categorized facts with optional tags:
|
|
206
102
|
```markdown
|
|
207
|
-
- [
|
|
103
|
+
- [decision] Use JWT for authentication #security
|
|
104
|
+
- [technique] Hash passwords with bcrypt #best-practice
|
|
105
|
+
- [requirement] Support OAuth 2.0 providers
|
|
208
106
|
```
|
|
209
107
|
|
|
210
|
-
|
|
108
|
+
### Relations
|
|
211
109
|
|
|
110
|
+
Directional links between entities:
|
|
212
111
|
```markdown
|
|
213
|
-
-
|
|
112
|
+
- implements [[Authentication Spec]]
|
|
113
|
+
- requires [[User Database]]
|
|
114
|
+
- extends [[Base Security Model]]
|
|
214
115
|
```
|
|
215
116
|
|
|
216
|
-
**Common
|
|
217
|
-
|
|
218
|
-
- Categories: `[idea]`, `[decision]`, `[question]`, `[fact]`, `[requirement]`, `[technique]`, `[recipe]`, `[preference]`
|
|
219
|
-
- Relations: `relates_to`, `implements`, `requires`, `extends`, `part_of`, `pairs_with`, `inspired_by`,
|
|
220
|
-
`originated_from`
|
|
221
|
-
|
|
222
|
-
## When to Record Context
|
|
223
|
-
|
|
224
|
-
**Always consider recording context when**:
|
|
225
|
-
|
|
226
|
-
1. Users make decisions or reach conclusions
|
|
227
|
-
2. Important information emerges during conversation
|
|
228
|
-
3. Multiple related topics are discussed
|
|
229
|
-
4. The conversation contains information that might be useful later
|
|
230
|
-
5. Plans, tasks, or action items are mentioned
|
|
117
|
+
**Common relation types:** `relates_to`, `implements`, `requires`, `extends`, `part_of`, `contrasts_with`
|
|
231
118
|
|
|
232
|
-
|
|
119
|
+
### Forward References
|
|
233
120
|
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
121
|
+
Reference entities that don't exist yet:
|
|
122
|
+
```python
|
|
123
|
+
# Create note with forward reference
|
|
124
|
+
await write_note(
|
|
125
|
+
title="Login Flow",
|
|
126
|
+
content="## Relations\n- requires [[OAuth Provider]]", # Doesn't exist yet
|
|
127
|
+
folder="auth",
|
|
128
|
+
project="main"
|
|
129
|
+
)
|
|
243
130
|
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
131
|
+
# Later, create referenced entity
|
|
132
|
+
await write_note(
|
|
133
|
+
title="OAuth Provider",
|
|
134
|
+
content="# OAuth Provider\n...",
|
|
135
|
+
folder="auth",
|
|
136
|
+
project="main"
|
|
137
|
+
)
|
|
138
|
+
# → Relation automatically resolved
|
|
139
|
+
```
|
|
247
140
|
|
|
248
|
-
|
|
249
|
-
await write_note(
|
|
250
|
-
title="Search Functionality Discussion",
|
|
251
|
-
content="# Search Functionality Discussion\n...",
|
|
252
|
-
folder="discussions"
|
|
253
|
-
)
|
|
254
|
-
```
|
|
141
|
+
## Best Practices
|
|
255
142
|
|
|
256
|
-
|
|
257
|
-
```
|
|
258
|
-
Human: "Take a look at memory://specs/search"
|
|
143
|
+
### 1. Project Management
|
|
259
144
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
```
|
|
145
|
+
**Single-project users:**
|
|
146
|
+
- Enable `default_project_mode=true`
|
|
147
|
+
- Simpler tool calls
|
|
264
148
|
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
149
|
+
**Multi-project users:**
|
|
150
|
+
- Keep `default_project_mode=false`
|
|
151
|
+
- Always specify project explicitly
|
|
268
152
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
153
|
+
**Discovery:**
|
|
154
|
+
```python
|
|
155
|
+
# Start with discovery
|
|
156
|
+
projects = await list_memory_projects()
|
|
273
157
|
|
|
274
|
-
|
|
158
|
+
# Cross-project activity (no project param = all projects)
|
|
159
|
+
activity = await recent_activity()
|
|
275
160
|
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
- Changes need to be synced by the user (usually automatic)
|
|
280
|
-
- Always verify information is current with `recent_activity()`
|
|
161
|
+
# Or specific project
|
|
162
|
+
activity = await recent_activity(project="main")
|
|
163
|
+
```
|
|
281
164
|
|
|
282
|
-
2.
|
|
283
|
-
- Start with specific entities
|
|
284
|
-
- Follow meaningful relations
|
|
285
|
-
- Check recent changes
|
|
286
|
-
- Build context incrementally
|
|
287
|
-
- Combine related information
|
|
165
|
+
### 2. Building Rich Graphs
|
|
288
166
|
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
- Keep files organized in logical folders
|
|
167
|
+
**Always include:**
|
|
168
|
+
- 3-5 observations per note
|
|
169
|
+
- 2-3 relations per note
|
|
170
|
+
- Meaningful categories and relation types
|
|
294
171
|
|
|
295
|
-
|
|
172
|
+
**Search before creating:**
|
|
173
|
+
```python
|
|
174
|
+
# Find existing entities to reference
|
|
175
|
+
results = await search_notes(query="authentication", project="main")
|
|
176
|
+
# Use exact titles in [[WikiLinks]]
|
|
177
|
+
```
|
|
296
178
|
|
|
297
|
-
###
|
|
179
|
+
### 3. Writing Effective Notes
|
|
298
180
|
|
|
181
|
+
**Structure:**
|
|
299
182
|
```markdown
|
|
300
|
-
#
|
|
183
|
+
# Title
|
|
301
184
|
|
|
302
185
|
## Context
|
|
303
|
-
|
|
304
|
-
I've experimented with various brewing methods including French press, pour over, and espresso.
|
|
305
|
-
|
|
306
|
-
## Decision
|
|
307
|
-
|
|
308
|
-
Pour over is my preferred method for light to medium roasts because it highlights subtle flavors and offers more control
|
|
309
|
-
over the extraction.
|
|
186
|
+
Background information
|
|
310
187
|
|
|
311
188
|
## Observations
|
|
312
|
-
|
|
313
|
-
- [
|
|
314
|
-
- [preference] Water temperature between 195-205°F works best #temperature
|
|
315
|
-
- [equipment] Gooseneck kettle provides better control of water flow #tools
|
|
189
|
+
- [category] Fact with #tags
|
|
190
|
+
- [category] Another fact
|
|
316
191
|
|
|
317
192
|
## Relations
|
|
318
|
-
|
|
319
|
-
- pairs_with [[Light Roast Beans]]
|
|
320
|
-
- contrasts_with [[French Press Method]]
|
|
321
|
-
- requires [[Proper Grinding Technique]]
|
|
193
|
+
- relation_type [[Exact Entity Title]]
|
|
322
194
|
```
|
|
323
195
|
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
```markdown
|
|
327
|
-
# Garden Planning
|
|
328
|
-
|
|
329
|
-
## Overview
|
|
196
|
+
**Categories:** `[idea]`, `[decision]`, `[fact]`, `[technique]`, `[requirement]`
|
|
330
197
|
|
|
331
|
-
|
|
198
|
+
### 4. Error Handling
|
|
332
199
|
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
- contains [[Herb Garden]]
|
|
343
|
-
- implements [[Organic Gardening Principles]]
|
|
200
|
+
**Missing project:**
|
|
201
|
+
```python
|
|
202
|
+
try:
|
|
203
|
+
await search_notes(query="test") # Missing project parameter - will error
|
|
204
|
+
except:
|
|
205
|
+
# Show available projects
|
|
206
|
+
projects = await list_memory_projects()
|
|
207
|
+
# Then retry with project
|
|
208
|
+
results = await search_notes(query="test", project=projects[0].name)
|
|
344
209
|
```
|
|
345
210
|
|
|
346
|
-
|
|
211
|
+
**Forward references:**
|
|
212
|
+
```python
|
|
213
|
+
# Check response for unresolved relations
|
|
214
|
+
response = await write_note(
|
|
215
|
+
title="New Topic",
|
|
216
|
+
content="## Relations\n- relates_to [[Future Topic]]",
|
|
217
|
+
folder="notes",
|
|
218
|
+
project="main"
|
|
219
|
+
)
|
|
220
|
+
# Forward refs will resolve when target created
|
|
221
|
+
```
|
|
347
222
|
|
|
348
|
-
|
|
349
|
-
# Recipe Improvement Discussion
|
|
223
|
+
### 5. Recording Context
|
|
350
224
|
|
|
351
|
-
|
|
225
|
+
**Ask permission:**
|
|
226
|
+
> "Would you like me to save our discussion about [topic] to Basic Memory?"
|
|
352
227
|
|
|
353
|
-
|
|
228
|
+
**Confirm when done:**
|
|
229
|
+
> "I've saved our discussion to Basic Memory."
|
|
354
230
|
|
|
355
|
-
|
|
231
|
+
**What to record:**
|
|
232
|
+
- Decisions and rationales
|
|
233
|
+
- Important discoveries
|
|
234
|
+
- Action items and plans
|
|
235
|
+
- Connected topics
|
|
356
236
|
|
|
357
|
-
|
|
358
|
-
- [solution] Chilling dough for 24 hours improves flavor and reduces spreading #technique
|
|
359
|
-
- [decision] Will use brown butter instead of regular butter #flavor
|
|
237
|
+
## Common Patterns
|
|
360
238
|
|
|
361
|
-
|
|
239
|
+
### Capture Decision
|
|
362
240
|
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
241
|
+
```python
|
|
242
|
+
await write_note(
|
|
243
|
+
title="DB Choice",
|
|
244
|
+
content="""# DB Choice\n## Decision\nUse PostgreSQL\n## Observations\n- [requirement] ACID compliance #reliability\n- [decision] PostgreSQL over MySQL\n## Relations\n- implements [[Data Architecture]]""",
|
|
245
|
+
folder="decisions",
|
|
246
|
+
project="main"
|
|
247
|
+
)
|
|
366
248
|
```
|
|
367
249
|
|
|
368
|
-
###
|
|
369
|
-
|
|
370
|
-
When creating relations, you can:
|
|
371
|
-
|
|
372
|
-
1. Reference existing entities by their exact title
|
|
373
|
-
2. Create forward references to entities that don't exist yet
|
|
250
|
+
### Link Topics & Build Context
|
|
374
251
|
|
|
375
252
|
```python
|
|
376
|
-
#
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
search_results = await search_notes(query="travel")
|
|
380
|
-
existing_entities = [result.title for result in search_results.primary_results]
|
|
253
|
+
# Link bidirectionally
|
|
254
|
+
await write_note(title="API Auth", content="## Relations\n- part_of [[API Design]]", folder="api", project="main")
|
|
255
|
+
await edit_note(identifier="API Design", operation="append", content="\n- includes [[API Auth]]", project="main")
|
|
381
256
|
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
# Prepare relations section - include both existing and forward references
|
|
387
|
-
relations_section = "## Relations\n"
|
|
388
|
-
|
|
389
|
-
# Existing reference - exact match to known entity
|
|
390
|
-
if packing_tips_exists:
|
|
391
|
-
relations_section += "- references [[Packing Tips]]\n"
|
|
392
|
-
else:
|
|
393
|
-
# Forward reference - will be linked when that entity is created later
|
|
394
|
-
relations_section += "- references [[Packing Tips]]\n"
|
|
395
|
-
|
|
396
|
-
# Another possible reference
|
|
397
|
-
if japan_travel_exists:
|
|
398
|
-
relations_section += "- part_of [[Japan Travel Guide]]\n"
|
|
399
|
-
|
|
400
|
-
# You can also check recently modified notes to reference them
|
|
401
|
-
recent = await recent_activity(timeframe="1 week")
|
|
402
|
-
recent_titles = [item.title for item in recent.primary_results]
|
|
403
|
-
|
|
404
|
-
if "Transportation Options" in recent_titles:
|
|
405
|
-
relations_section += "- relates_to [[Transportation Options]]\n"
|
|
406
|
-
|
|
407
|
-
# Always include meaningful forward references, even if they don't exist yet
|
|
408
|
-
relations_section += "- located_in [[Tokyo]]\n"
|
|
409
|
-
relations_section += "- visited_during [[Spring 2023 Trip]]\n"
|
|
257
|
+
# Search and build context
|
|
258
|
+
results = await search_notes(query="authentication", project="main")
|
|
259
|
+
context = await build_context(url=f"memory://{results[0].permalink}", project="main", depth=2)
|
|
260
|
+
```
|
|
410
261
|
|
|
411
|
-
|
|
412
|
-
content = f"""# Tokyo Neighborhood Guide
|
|
262
|
+
## Tool Quick Reference
|
|
413
263
|
|
|
414
|
-
|
|
415
|
-
|
|
264
|
+
| Tool | Purpose | Key Params |
|
|
265
|
+
|------|---------|------------|
|
|
266
|
+
| `write_note` | Create/update | title, content, folder, project |
|
|
267
|
+
| `read_note` | Read content | identifier, project |
|
|
268
|
+
| `edit_note` | Modify existing | identifier, operation, content, project |
|
|
269
|
+
| `search_notes` | Find notes | query, project |
|
|
270
|
+
| `build_context` | Graph traversal | url, depth, project |
|
|
271
|
+
| `recent_activity` | Recent changes | timeframe, project |
|
|
272
|
+
| `list_memory_projects` | Show projects | (none) |
|
|
416
273
|
|
|
417
|
-
##
|
|
418
|
-
- [area] Shibuya is a busy shopping district #shopping
|
|
419
|
-
- [transportation] Yamanote Line connects major neighborhoods #transit
|
|
420
|
-
- [recommendation] Visit Shimokitazawa for vintage shopping #unique
|
|
421
|
-
- [tip] Get a Suica card for easy train travel #convenience
|
|
422
|
-
|
|
423
|
-
{relations_section}
|
|
424
|
-
"""
|
|
425
|
-
|
|
426
|
-
result = await write_note(
|
|
427
|
-
title="Tokyo Neighborhood Guide",
|
|
428
|
-
content=content,
|
|
429
|
-
folder="travel"
|
|
430
|
-
)
|
|
431
|
-
|
|
432
|
-
# You can check which relations were resolved and which are forward references
|
|
433
|
-
if result and 'relations' in result:
|
|
434
|
-
resolved = [r['to_name'] for r in result['relations'] if r.get('target_id')]
|
|
435
|
-
forward_refs = [r['to_name'] for r in result['relations'] if not r.get('target_id')]
|
|
436
|
-
|
|
437
|
-
print(f"Resolved relations: {resolved}")
|
|
438
|
-
print(f"Forward references that will be resolved later: {forward_refs}")
|
|
439
|
-
```
|
|
274
|
+
## memory:// URL Format
|
|
440
275
|
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
1. **Missing Content**
|
|
446
|
-
```python
|
|
447
|
-
try:
|
|
448
|
-
content = await read_note("Document")
|
|
449
|
-
except:
|
|
450
|
-
# Try search instead
|
|
451
|
-
results = await search_notes(query="Document")
|
|
452
|
-
if results and results.primary_results:
|
|
453
|
-
# Found something similar
|
|
454
|
-
content = await read_note(results.primary_results[0].permalink)
|
|
455
|
-
```
|
|
456
|
-
|
|
457
|
-
2. **Forward References (Unresolved Relations)**
|
|
458
|
-
```python
|
|
459
|
-
response = await write_note(
|
|
460
|
-
title="My Note",
|
|
461
|
-
content="Content with [[Forward Reference]]",
|
|
462
|
-
folder="notes"
|
|
463
|
-
)
|
|
464
|
-
# Check for forward references (unresolved relations)
|
|
465
|
-
forward_refs = []
|
|
466
|
-
for relation in response.get('relations', []):
|
|
467
|
-
if not relation.get('target_id'):
|
|
468
|
-
forward_refs.append(relation.get('to_name'))
|
|
469
|
-
|
|
470
|
-
if forward_refs:
|
|
471
|
-
# This is a feature, not an error! Inform the user about forward references
|
|
472
|
-
print(f"Note created with forward references to: {forward_refs}")
|
|
473
|
-
print("These will be automatically linked when those notes are created.")
|
|
474
|
-
|
|
475
|
-
# Optionally suggest creating those entities now
|
|
476
|
-
print("Would you like me to create any of these notes now to complete the connections?")
|
|
477
|
-
```
|
|
478
|
-
|
|
479
|
-
3. **Project Discovery Issues**
|
|
480
|
-
```python
|
|
481
|
-
# If user asks about content but no default project is configured
|
|
482
|
-
try:
|
|
483
|
-
results = await search_notes(query="user query")
|
|
484
|
-
except Exception as e:
|
|
485
|
-
if "project" in str(e).lower():
|
|
486
|
-
# Show available projects and ask user to choose
|
|
487
|
-
projects = await list_memory_projects()
|
|
488
|
-
print(f"Available projects: {[p.name for p in projects]}")
|
|
489
|
-
print("Which project should I search in?")
|
|
490
|
-
```
|
|
491
|
-
|
|
492
|
-
4. **Sync Issues**
|
|
493
|
-
```python
|
|
494
|
-
# If information seems outdated
|
|
495
|
-
activity = await recent_activity(timeframe="1 hour")
|
|
496
|
-
if not activity or not activity.primary_results:
|
|
497
|
-
print("It seems there haven't been recent updates. You might need to run 'basic-memory sync'.")
|
|
498
|
-
```
|
|
276
|
+
- `memory://title` - By title
|
|
277
|
+
- `memory://folder/title` - By folder + title
|
|
278
|
+
- `memory://permalink` - By permalink
|
|
279
|
+
- `memory://folder/*` - All in folder
|
|
499
280
|
|
|
500
|
-
|
|
281
|
+
For full documentation: https://docs.basicmemory.com
|
|
501
282
|
|
|
502
|
-
|
|
503
|
-
- **For new users**: Call `recent_activity()` without project parameter to discover active projects and get recommendations
|
|
504
|
-
- **For known projects**: Use explicit project parameters when switching between multiple projects
|
|
505
|
-
- **For single-project users**: Rely on default_project_mode for convenience
|
|
506
|
-
- **When uncertain**: Use `list_memory_projects()` to show available options and ask the user
|
|
507
|
-
- **Remember choices**: Once a user indicates their preferred project, use it consistently throughout the conversation
|
|
508
|
-
|
|
509
|
-
2. **Proactively Record Context**
|
|
510
|
-
- Offer to capture important discussions
|
|
511
|
-
- Record decisions, rationales, and conclusions
|
|
512
|
-
- Link to related topics
|
|
513
|
-
- Ask for permission first: "Would you like me to save our discussion about [topic]?"
|
|
514
|
-
- Confirm when complete: "I've saved our discussion to Basic Memory"
|
|
515
|
-
|
|
516
|
-
3. **Create a Rich Semantic Graph**
|
|
517
|
-
- **Add meaningful observations**: Include at least 3-5 categorized observations in each note
|
|
518
|
-
- **Create deliberate relations**: Connect each note to at least 2-3 related entities
|
|
519
|
-
- **Use existing entities**: Before creating a new relation, search for existing entities
|
|
520
|
-
- **Verify wikilinks**: When referencing `[[Entity]]`, use exact titles of existing notes
|
|
521
|
-
- **Check accuracy**: Use `search_notes()` or `recent_activity()` to confirm entity titles
|
|
522
|
-
- **Use precise relation types**: Choose specific relation types that convey meaning (e.g., "implements" instead
|
|
523
|
-
of "relates_to")
|
|
524
|
-
- **Consider bidirectional relations**: When appropriate, create inverse relations in both entities
|
|
525
|
-
|
|
526
|
-
4. **Structure Content Thoughtfully**
|
|
527
|
-
- Use clear, descriptive titles
|
|
528
|
-
- Organize with logical sections (Context, Decision, Implementation, etc.)
|
|
529
|
-
- Include relevant context and background
|
|
530
|
-
- Add semantic observations with appropriate categories
|
|
531
|
-
- Use a consistent format for similar types of notes
|
|
532
|
-
- Balance detail with conciseness
|
|
533
|
-
|
|
534
|
-
5. **Navigate Knowledge Effectively**
|
|
535
|
-
- Start with specific searches using `search_notes()`
|
|
536
|
-
- Follow relation paths with `build_context()`
|
|
537
|
-
- Combine information from multiple sources
|
|
538
|
-
- Verify information is current with `recent_activity()`
|
|
539
|
-
- Build a complete picture before responding
|
|
540
|
-
- Use appropriate project context for searches
|
|
541
|
-
|
|
542
|
-
6. **Help Users Maintain Their Knowledge**
|
|
543
|
-
- Suggest organizing related topics across projects when appropriate
|
|
544
|
-
- Identify potential duplicates using search
|
|
545
|
-
- Recommend adding relations between topics
|
|
546
|
-
- Offer to create summaries of scattered information
|
|
547
|
-
- Suggest potential missing relations: "I notice this might relate to [topic], would you like me to add that connection?"
|
|
548
|
-
- Help users decide when to use explicit vs default project parameters
|
|
549
|
-
|
|
550
|
-
Built with ♥️ b
|
|
551
|
-
y Basic Machines
|
|
283
|
+
Built with ♥️ by Basic Machines
|