pin-memory 0.3.1__tar.gz → 0.3.2__tar.gz
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.
- {pin_memory-0.3.1 → pin_memory-0.3.2}/CHANGELOG.md +19 -0
- {pin_memory-0.3.1 → pin_memory-0.3.2}/PKG-INFO +9 -2
- {pin_memory-0.3.1 → pin_memory-0.3.2}/README.md +8 -1
- {pin_memory-0.3.1 → pin_memory-0.3.2}/openwiki/architecture/cli.md +19 -2
- {pin_memory-0.3.1 → pin_memory-0.3.2}/openwiki/quickstart.md +7 -2
- pin_memory-0.3.2/openwiki/workflows/usage.md +160 -0
- {pin_memory-0.3.1 → pin_memory-0.3.2}/pyproject.toml +1 -1
- {pin_memory-0.3.1 → pin_memory-0.3.2}/src/pin_memory/server.py +90 -40
- {pin_memory-0.3.1 → pin_memory-0.3.2}/tests/test_server.py +103 -2
- {pin_memory-0.3.1 → pin_memory-0.3.2}/uv.lock +3 -3
- pin_memory-0.3.1/openwiki/workflows/usage.md +0 -346
- {pin_memory-0.3.1 → pin_memory-0.3.2}/.github/workflows/publish.yml +0 -0
- {pin_memory-0.3.1 → pin_memory-0.3.2}/.gitignore +0 -0
- {pin_memory-0.3.1 → pin_memory-0.3.2}/AGENTS.md +0 -0
- {pin_memory-0.3.1 → pin_memory-0.3.2}/openwiki/.last-update.json +0 -0
- {pin_memory-0.3.1 → pin_memory-0.3.2}/openwiki/architecture/mcp.md +0 -0
- {pin_memory-0.3.1 → pin_memory-0.3.2}/openwiki/architecture/memory.md +0 -0
- {pin_memory-0.3.1 → pin_memory-0.3.2}/openwiki/testing/unit-tests.md +0 -0
- {pin_memory-0.3.1 → pin_memory-0.3.2}/openwiki/workflows/ci-cd.md +0 -0
- {pin_memory-0.3.1 → pin_memory-0.3.2}/src/pin_memory/__init__.py +0 -0
- {pin_memory-0.3.1 → pin_memory-0.3.2}/src/pin_memory/main.py +0 -0
- {pin_memory-0.3.1 → pin_memory-0.3.2}/tests/__init__.py +0 -0
|
@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
## [0.3.2] - 2026-11-19
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
- `install` now replaces an existing Pin fragment in place instead of skipping, so
|
|
14
|
+
re-running with a different `--workspace` rebinds the project, and omitting
|
|
15
|
+
`--workspace` clears a stale binding. Surrounding `AGENTS.md` content is preserved.
|
|
16
|
+
- Behavioural constraints (`recall` before the first task, `pin` only when explicitly
|
|
17
|
+
asked) are now also in the MCP tool descriptions, where the model sees them at the
|
|
18
|
+
point of use, not only in the installed `AGENTS.md` fragment.
|
|
19
|
+
|
|
20
|
+
### Added
|
|
21
|
+
- `--version` CLI option that reports the installed `pin-memory` version.
|
|
22
|
+
- Unit tests for `install`/`AGENTS.md` fragment generation and updating.
|
|
23
|
+
|
|
24
|
+
### Fixed
|
|
25
|
+
- Deduplicated the repeated sections in `openwiki/workflows/usage.md`.
|
|
26
|
+
|
|
8
27
|
## [0.3.1] - 2026-09-28
|
|
9
28
|
|
|
10
29
|
### Fixed
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: pin-memory
|
|
3
|
-
Version: 0.3.
|
|
3
|
+
Version: 0.3.2
|
|
4
4
|
Summary: A Memory MCP server for pinning and recalling factoids.
|
|
5
5
|
Project-URL: Homepage, https://github.com/scartill/pin-memory
|
|
6
6
|
Project-URL: Changelog, https://github.com/scartill/pin-memory/blob/main/CHANGELOG.md
|
|
@@ -39,10 +39,13 @@ uv run pin-memory mcp
|
|
|
39
39
|
Pin Memory provides a CLI for managing factoids:
|
|
40
40
|
|
|
41
41
|
```bash
|
|
42
|
+
# Show installed version
|
|
43
|
+
pin-memory --version
|
|
44
|
+
|
|
42
45
|
# List all factoids
|
|
43
46
|
pin-memory show
|
|
44
47
|
|
|
45
|
-
# Install agent instructions to AGENTS.md
|
|
48
|
+
# Install agent instructions to AGENTS.md (re-run to rebind the workspace)
|
|
46
49
|
pin-memory install --workspace my-workspace
|
|
47
50
|
|
|
48
51
|
# Launch the MCP server
|
|
@@ -86,9 +89,13 @@ Stores a factoid in memory.
|
|
|
86
89
|
- `factoid`: The content of the factoid.
|
|
87
90
|
- `location`: "global", "project", or "workspace/<name>".
|
|
88
91
|
|
|
92
|
+
The tool description instructs agents to pin only when explicitly asked, so the model
|
|
93
|
+
sees that constraint at the point where it decides to write.
|
|
94
|
+
|
|
89
95
|
### `recall`
|
|
90
96
|
|
|
91
97
|
Recalls all pinned factoids from global, requested workspace, and local project scopes.
|
|
98
|
+
The tool description tells agents to call it before the first task.
|
|
92
99
|
|
|
93
100
|
- `workspace`: Optional name of the workspace.
|
|
94
101
|
|
|
@@ -27,10 +27,13 @@ uv run pin-memory mcp
|
|
|
27
27
|
Pin Memory provides a CLI for managing factoids:
|
|
28
28
|
|
|
29
29
|
```bash
|
|
30
|
+
# Show installed version
|
|
31
|
+
pin-memory --version
|
|
32
|
+
|
|
30
33
|
# List all factoids
|
|
31
34
|
pin-memory show
|
|
32
35
|
|
|
33
|
-
# Install agent instructions to AGENTS.md
|
|
36
|
+
# Install agent instructions to AGENTS.md (re-run to rebind the workspace)
|
|
34
37
|
pin-memory install --workspace my-workspace
|
|
35
38
|
|
|
36
39
|
# Launch the MCP server
|
|
@@ -74,9 +77,13 @@ Stores a factoid in memory.
|
|
|
74
77
|
- `factoid`: The content of the factoid.
|
|
75
78
|
- `location`: "global", "project", or "workspace/<name>".
|
|
76
79
|
|
|
80
|
+
The tool description instructs agents to pin only when explicitly asked, so the model
|
|
81
|
+
sees that constraint at the point where it decides to write.
|
|
82
|
+
|
|
77
83
|
### `recall`
|
|
78
84
|
|
|
79
85
|
Recalls all pinned factoids from global, requested workspace, and local project scopes.
|
|
86
|
+
The tool description tells agents to call it before the first task.
|
|
80
87
|
|
|
81
88
|
- `workspace`: Optional name of the workspace.
|
|
82
89
|
|
|
@@ -2,6 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
Pin Memory provides a CLI for managing factoids and installing agent instructions. The CLI is implemented using the `click` library (`/src/pin_memory/server.py`).
|
|
4
4
|
|
|
5
|
+
## Global Options
|
|
6
|
+
|
|
7
|
+
### `--version`
|
|
8
|
+
|
|
9
|
+
Prints the installed `pin-memory` version and exits.
|
|
10
|
+
|
|
11
|
+
**Example:**
|
|
12
|
+
```bash
|
|
13
|
+
pin-memory --version
|
|
14
|
+
pin-memory, version 0.3.1
|
|
15
|
+
```
|
|
16
|
+
|
|
5
17
|
## Commands
|
|
6
18
|
|
|
7
19
|
### `pin-memory show`
|
|
@@ -27,7 +39,8 @@ Workspace: my-workspace
|
|
|
27
39
|
|
|
28
40
|
### `pin-memory install`
|
|
29
41
|
|
|
30
|
-
Installs agent instructions to `AGENTS.md`.
|
|
42
|
+
Installs agent instructions to `AGENTS.md`. The fragment is delimited by
|
|
43
|
+
`<!-- pin mcp start -->` and `<!-- pin mcp stop -->`.
|
|
31
44
|
|
|
32
45
|
**Options:**
|
|
33
46
|
- `--workspace, -w`: Optional workspace name to include in the instructions.
|
|
@@ -40,10 +53,14 @@ pin-memory install --workspace my-workspace
|
|
|
40
53
|
**Output (`AGENTS.md`):**
|
|
41
54
|
```markdown
|
|
42
55
|
<!-- pin mcp start -->
|
|
43
|
-
Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. The Pin workspace for this project is `my-workspace`.
|
|
56
|
+
Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. Do not pin new factoids unless explicitly asked to do so. The Pin workspace for this project is `my-workspace`.
|
|
44
57
|
<!-- pin mcp stop -->
|
|
45
58
|
```
|
|
46
59
|
|
|
60
|
+
Re-running the command replaces the existing fragment instead of skipping, so changing
|
|
61
|
+
`--workspace` rebinds the project and omitting it removes a stale binding. Text outside
|
|
62
|
+
the markers is preserved.
|
|
63
|
+
|
|
47
64
|
### `pin-memory mcp`
|
|
48
65
|
|
|
49
66
|
Launches the MCP server (stdio).
|
|
@@ -12,7 +12,9 @@ It enables **LLMs and agents** to autonomously remember and recall information,
|
|
|
12
12
|
- **Pin factoids** in global, workspace-specific, or project-local storage.
|
|
13
13
|
- **Recall factoids** based on current context (global + workspace + project).
|
|
14
14
|
- **MCP tools** (`pin`, `recall`) for LLMs to autonomously manage memory.
|
|
15
|
-
- **CLI** for managing factoids (`show`, `install`, `mcp`)
|
|
15
|
+
- **CLI** for managing factoids (`show`, `install`, `mcp`); `install` binds a project to
|
|
16
|
+
a workspace via `AGENTS.md`, which tool descriptions cannot do since they are
|
|
17
|
+
server-global.
|
|
16
18
|
- **Agent integration** for fetching factoids at task start.
|
|
17
19
|
- **Frontmatter stripping**: Removes YAML frontmatter from factoid files.
|
|
18
20
|
|
|
@@ -76,11 +78,14 @@ pin-memory show
|
|
|
76
78
|
pin-memory install --workspace my-workspace
|
|
77
79
|
```
|
|
78
80
|
|
|
81
|
+
Re-running the command replaces the fragment in place, so pass a new `--workspace` to
|
|
82
|
+
rebind the project.
|
|
83
|
+
|
|
79
84
|
**Output (`AGENTS.md`):**
|
|
80
85
|
|
|
81
86
|
```markdown
|
|
82
87
|
<!-- pin mcp start -->
|
|
83
|
-
Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. The Pin workspace for this project is `my-workspace`.
|
|
88
|
+
Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. Do not pin new factoids unless explicitly asked to do so. The Pin workspace for this project is `my-workspace`.
|
|
84
89
|
<!-- pin mcp stop -->
|
|
85
90
|
```
|
|
86
91
|
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# Usage
|
|
2
|
+
|
|
3
|
+
This page explains how to use Pin Memory for managing factoids and integrating with agents.
|
|
4
|
+
|
|
5
|
+
## Managing Factoids
|
|
6
|
+
|
|
7
|
+
### Pin a Factoid
|
|
8
|
+
|
|
9
|
+
Use the `pin` MCP tool to store a factoid in memory.
|
|
10
|
+
|
|
11
|
+
```json
|
|
12
|
+
{
|
|
13
|
+
"tool": "pin",
|
|
14
|
+
"factoid_name": "api_key",
|
|
15
|
+
"factoid": "sk-12345",
|
|
16
|
+
"location": "global"
|
|
17
|
+
}
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
**Response:**
|
|
21
|
+
|
|
22
|
+
```json
|
|
23
|
+
{
|
|
24
|
+
"output": "Factoid 'api_key' pinned to 'global' successfully."
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Factoids can also be written manually, as one Markdown file per factoid:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
mkdir -p ~/.scartill/pin
|
|
32
|
+
echo "sk-12345" > ~/.scartill/pin/api_key.md
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### Recall Factoids
|
|
36
|
+
|
|
37
|
+
Use the `recall` MCP tool to retrieve factoids from the global, workspace, and project scopes in one call.
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"tool": "recall",
|
|
42
|
+
"workspace": "my-workspace"
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
**Response:**
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"output": "sk-12345\n\nRemember to update the docs!"
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
YAML frontmatter is stripped from factoid files before the content is returned, so metadata such as `title:` or `tags:` never reaches the agent.
|
|
55
|
+
|
|
56
|
+
### List All Factoids
|
|
57
|
+
|
|
58
|
+
Use the `show` CLI command to list all factoids grouped by scope.
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
pin-memory show
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**Example Output:**
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
Global Factoids
|
|
68
|
+
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
|
|
69
|
+
┃ Name ┃ Content ┃
|
|
70
|
+
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
|
|
71
|
+
│ api_key │ sk-12345 │
|
|
72
|
+
└────────────┴───────────────────────────────────────────┘
|
|
73
|
+
|
|
74
|
+
Workspace: my-workspace
|
|
75
|
+
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
|
|
76
|
+
┃ Name ┃ Content ┃
|
|
77
|
+
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
|
|
78
|
+
│ team_note │ Remember to update the docs! │
|
|
79
|
+
└────────────┴───────────────────────────────────────────┘
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Scopes
|
|
83
|
+
|
|
84
|
+
| Scope | Description | Storage Location |
|
|
85
|
+
|------------|--------------------------------------------------------------------|-----------------------------------------------|
|
|
86
|
+
| Global | User-wide factoids, available across all projects and workspaces. | `~/.scartill/pin` |
|
|
87
|
+
| Workspace | Factoids specific to a workspace (e.g., a team or project context). | `~/.scartill/pin/workspaces/<workspace_name>` |
|
|
88
|
+
| Project | Factoids local to the current project. | `.pin` in the current working directory |
|
|
89
|
+
|
|
90
|
+
`recall` always reads global and project factoids, plus the workspace passed in its argument.
|
|
91
|
+
|
|
92
|
+
## Agent Integration
|
|
93
|
+
|
|
94
|
+
### Install Agent Instructions
|
|
95
|
+
|
|
96
|
+
The `install` command writes a delimited fragment into `AGENTS.md`, binding project
|
|
97
|
+
instructions to the Pin MCP server.
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
pin-memory install --workspace my-workspace
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
**Output (`AGENTS.md`):**
|
|
104
|
+
|
|
105
|
+
```markdown
|
|
106
|
+
<!-- pin mcp start -->
|
|
107
|
+
Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. Do not pin new factoids unless explicitly asked to do so. The Pin workspace for this project is `my-workspace`.
|
|
108
|
+
<!-- pin mcp stop -->
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
The command is idempotent: re-running it replaces the existing fragment in place rather
|
|
112
|
+
than skipping, so changing `--workspace` rebinds the project, and omitting `--workspace`
|
|
113
|
+
removes a previously installed binding. Text outside the markers is left untouched.
|
|
114
|
+
|
|
115
|
+
Why this exists alongside the tool descriptions:
|
|
116
|
+
|
|
117
|
+
- **Timing.** Tool descriptions only inform a decision once the model already considers a
|
|
118
|
+
tool relevant. The fragment tells the agent to `recall` *before* the first task, which
|
|
119
|
+
no server-side description can enforce.
|
|
120
|
+
- **Project binding.** The workspace name is per-project configuration, while an MCP tool
|
|
121
|
+
description is server-global and static.
|
|
122
|
+
- **Clients without MCP.** Agents that never load the server still read `AGENTS.md`.
|
|
123
|
+
|
|
124
|
+
### Fetching Factoids at Task Start
|
|
125
|
+
|
|
126
|
+
When an agent starts a task, it should:
|
|
127
|
+
|
|
128
|
+
1. Use the `recall` MCP tool to fetch factoids from global, workspace, and project scopes.
|
|
129
|
+
2. Use the factoids as **important instructions** for the task.
|
|
130
|
+
|
|
131
|
+
### Example Workflow
|
|
132
|
+
|
|
133
|
+
1. **Pin factoids** for the workspace:
|
|
134
|
+
```json
|
|
135
|
+
{
|
|
136
|
+
"tool": "pin",
|
|
137
|
+
"factoid_name": "team_note",
|
|
138
|
+
"factoid": "Remember to update the docs!",
|
|
139
|
+
"location": "workspace/my-workspace"
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
2. **Install agent instructions** for the workspace:
|
|
144
|
+
```bash
|
|
145
|
+
pin-memory install --workspace my-workspace
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
3. **Agent fetches factoids** at task start:
|
|
149
|
+
```json
|
|
150
|
+
{
|
|
151
|
+
"tool": "recall",
|
|
152
|
+
"workspace": "my-workspace"
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
4. **Agent uses factoids** as instructions for the task.
|
|
157
|
+
|
|
158
|
+
## Source Reference
|
|
159
|
+
|
|
160
|
+
- [`/src/pin_memory/server.py`](file:///src/pin_memory/server.py): Core logic and CLI.
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
from importlib import metadata
|
|
1
2
|
from pathlib import Path
|
|
2
3
|
from typing import Literal
|
|
3
4
|
|
|
@@ -9,6 +10,12 @@ from rich.console import Console
|
|
|
9
10
|
from rich.table import Table
|
|
10
11
|
|
|
11
12
|
|
|
13
|
+
try:
|
|
14
|
+
__version__ = metadata.version("pin-memory")
|
|
15
|
+
except metadata.PackageNotFoundError:
|
|
16
|
+
__version__ = "unknown"
|
|
17
|
+
|
|
18
|
+
|
|
12
19
|
class MemoryManager:
|
|
13
20
|
"""Manages factoids stored in various scopes."""
|
|
14
21
|
|
|
@@ -61,7 +68,9 @@ class MemoryManager:
|
|
|
61
68
|
@staticmethod
|
|
62
69
|
def _strip_frontmatter(text: str) -> str:
|
|
63
70
|
"""Remove YAML frontmatter (--- delimited block at start of text)."""
|
|
64
|
-
return re.sub(
|
|
71
|
+
return re.sub(
|
|
72
|
+
r"\A---\s*\n(.*?\n)?---\s*\n?", "", text, count=1, flags=re.DOTALL
|
|
73
|
+
)
|
|
65
74
|
|
|
66
75
|
def _get_factoids(self, target_dir: Path) -> list[dict]:
|
|
67
76
|
"""Get all factoids from a specific directory as list of dicts {name, content}."""
|
|
@@ -128,7 +137,70 @@ class MemoryManager:
|
|
|
128
137
|
return results
|
|
129
138
|
|
|
130
139
|
|
|
140
|
+
PIN_START_MARKER = "<!-- pin mcp start -->"
|
|
141
|
+
PIN_STOP_MARKER = "<!-- pin mcp stop -->"
|
|
142
|
+
|
|
143
|
+
PIN_INSTRUCTIONS = (
|
|
144
|
+
"Before starting the first task, fetch all global and project factoids via Pin MCP "
|
|
145
|
+
"and use them as **important** instructions. Do not pin new factoids unless "
|
|
146
|
+
"explicitly asked to do so."
|
|
147
|
+
)
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def build_fragment(workspace: str | None = None) -> str:
|
|
151
|
+
"""Build the agent instructions fragment, optionally binding a workspace."""
|
|
152
|
+
instruction = PIN_INSTRUCTIONS
|
|
153
|
+
if workspace:
|
|
154
|
+
instruction += f" The Pin workspace for this project is `{workspace}`."
|
|
155
|
+
return f"{PIN_START_MARKER}\n{instruction}\n{PIN_STOP_MARKER}\n"
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
def upsert_fragment(content: str, fragment: str) -> str:
|
|
159
|
+
"""Replace an existing Pin fragment in place, or append a new one."""
|
|
160
|
+
pattern = re.compile(
|
|
161
|
+
re.escape(PIN_START_MARKER) + r".*?" + re.escape(PIN_STOP_MARKER) + r"\n?",
|
|
162
|
+
re.DOTALL,
|
|
163
|
+
)
|
|
164
|
+
if pattern.search(content):
|
|
165
|
+
return pattern.sub(lambda _: fragment, content, count=1)
|
|
166
|
+
|
|
167
|
+
separator = ""
|
|
168
|
+
if content and not content.endswith("\n"):
|
|
169
|
+
separator = "\n"
|
|
170
|
+
return f"{content}{separator}\n{fragment}"
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
def install_instructions(
|
|
174
|
+
agents_path: Path, workspace: str | None = None
|
|
175
|
+
) -> tuple[bool, str]:
|
|
176
|
+
"""Create or update the Pin fragment in an agent instructions file.
|
|
177
|
+
|
|
178
|
+
Returns a (changed, message) tuple.
|
|
179
|
+
"""
|
|
180
|
+
fragment = build_fragment(workspace)
|
|
181
|
+
name = agents_path.name
|
|
182
|
+
|
|
183
|
+
if agents_path.exists():
|
|
184
|
+
content = agents_path.read_text(encoding="utf-8")
|
|
185
|
+
updated = upsert_fragment(content, fragment)
|
|
186
|
+
if updated == content:
|
|
187
|
+
return False, f"{name} already contains the current Pin MCP fragment."
|
|
188
|
+
try:
|
|
189
|
+
agents_path.write_text(updated, encoding="utf-8")
|
|
190
|
+
except OSError as e:
|
|
191
|
+
return False, f"Error updating {name}: {e}"
|
|
192
|
+
action = "Updated" if PIN_START_MARKER in content else "Added"
|
|
193
|
+
return True, f"{action} Pin MCP fragment in {name}."
|
|
194
|
+
|
|
195
|
+
try:
|
|
196
|
+
agents_path.write_text(fragment, encoding="utf-8")
|
|
197
|
+
except OSError as e:
|
|
198
|
+
return False, f"Error creating {name}: {e}"
|
|
199
|
+
return True, f"Created {name} with Pin MCP fragment."
|
|
200
|
+
|
|
201
|
+
|
|
131
202
|
@click.group()
|
|
203
|
+
@click.version_option(version=__version__, prog_name="pin-memory")
|
|
132
204
|
def cli():
|
|
133
205
|
"""Pin MCP – Memory management across global, workspace, and project scopes."""
|
|
134
206
|
pass
|
|
@@ -177,47 +249,19 @@ def show():
|
|
|
177
249
|
"--workspace", "-w", help="Optional workspace name to include in the instructions."
|
|
178
250
|
)
|
|
179
251
|
def install(workspace: str | None) -> None:
|
|
180
|
-
"""Add agent instructions fragment
|
|
181
|
-
console = Console()
|
|
182
|
-
agents_file = Path("AGENTS.md")
|
|
183
|
-
|
|
184
|
-
start_marker = "<!-- pin mcp start -->"
|
|
185
|
-
stop_marker = "<!-- pin mcp stop -->"
|
|
186
|
-
|
|
187
|
-
instruction = (
|
|
188
|
-
"Before starting the first task, fetch all global and project factoids via Pin MCP "
|
|
189
|
-
"and use them as **important** instructions. Do not pin new factoids unless "
|
|
190
|
-
"explicitly asked to do so."
|
|
191
|
-
)
|
|
192
|
-
if workspace:
|
|
193
|
-
instruction += f" The Pin workspace for this project is `{workspace}`."
|
|
252
|
+
"""Add or update the agent instructions fragment in AGENTS.md.
|
|
194
253
|
|
|
195
|
-
fragment
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
# Append to existing file
|
|
205
|
-
try:
|
|
206
|
-
with agents_file.open("a", encoding="utf-8") as f:
|
|
207
|
-
# Ensure we start on a new line if the file doesn't end with one
|
|
208
|
-
if content and not content.endswith("\n"):
|
|
209
|
-
f.write("\n")
|
|
210
|
-
f.write(f"\n{fragment}")
|
|
211
|
-
console.print("[green]Pin MCP fragment added to AGENTS.md.[/green]")
|
|
212
|
-
except Exception as e:
|
|
213
|
-
console.print(f"[red]Error updating AGENTS.md: {e}[/red]")
|
|
254
|
+
Re-running updates the existing fragment in place, so changing
|
|
255
|
+
--workspace rebinds the project instead of being ignored.
|
|
256
|
+
"""
|
|
257
|
+
changed, message = install_instructions(Path("AGENTS.md"), workspace)
|
|
258
|
+
console = Console()
|
|
259
|
+
if changed:
|
|
260
|
+
console.print(f"[green]{message}[/green]")
|
|
261
|
+
elif message.startswith("Error"):
|
|
262
|
+
console.print(f"[red]{message}[/red]")
|
|
214
263
|
else:
|
|
215
|
-
|
|
216
|
-
try:
|
|
217
|
-
agents_file.write_text(fragment, encoding="utf-8")
|
|
218
|
-
console.print("[green]Created AGENTS.md with Pin MCP fragment.[/green]")
|
|
219
|
-
except Exception as e:
|
|
220
|
-
console.print(f"[red]Error creating AGENTS.md: {e}[/red]")
|
|
264
|
+
console.print(f"[yellow]{message}[/yellow]")
|
|
221
265
|
|
|
222
266
|
|
|
223
267
|
@cli.command("mcp")
|
|
@@ -232,6 +276,9 @@ def mcp_cmd():
|
|
|
232
276
|
) -> str:
|
|
233
277
|
"""Store a factoid in memory.
|
|
234
278
|
|
|
279
|
+
Only pin when explicitly asked to do so; never pin unprompted, and never pin
|
|
280
|
+
credentials or secrets unless the user names the factoid themselves.
|
|
281
|
+
|
|
235
282
|
If asked to pin to a workspace, use "workspace/<name>" for location. Example: "workspace/my-workspace".
|
|
236
283
|
|
|
237
284
|
If asked to pin locally or for the current projects, use "project" for location.
|
|
@@ -247,6 +294,9 @@ def mcp_cmd():
|
|
|
247
294
|
def recall(workspace: str | None = None) -> str:
|
|
248
295
|
"""Recall pinned factoids.
|
|
249
296
|
|
|
297
|
+
Call this before starting the first task in a session, and use the result as
|
|
298
|
+
important instructions for the rest of the work.
|
|
299
|
+
|
|
250
300
|
Returns global, requested workspace, and local project factoids.
|
|
251
301
|
|
|
252
302
|
Args:
|
|
@@ -2,7 +2,18 @@ import unittest
|
|
|
2
2
|
from pathlib import Path
|
|
3
3
|
import shutil
|
|
4
4
|
import tempfile
|
|
5
|
-
|
|
5
|
+
|
|
6
|
+
from click.testing import CliRunner
|
|
7
|
+
from pin_memory.server import (
|
|
8
|
+
__version__,
|
|
9
|
+
cli,
|
|
10
|
+
PIN_START_MARKER,
|
|
11
|
+
PIN_STOP_MARKER,
|
|
12
|
+
MemoryManager,
|
|
13
|
+
build_fragment,
|
|
14
|
+
install_instructions,
|
|
15
|
+
upsert_fragment,
|
|
16
|
+
)
|
|
6
17
|
|
|
7
18
|
|
|
8
19
|
class TestMemoryManager(unittest.TestCase):
|
|
@@ -59,7 +70,6 @@ class TestMemoryManager(unittest.TestCase):
|
|
|
59
70
|
self.assertIn("project fact", output)
|
|
60
71
|
self.assertEqual(output, "global fact\n\nproject fact")
|
|
61
72
|
|
|
62
|
-
|
|
63
73
|
def test_strip_frontmatter_removes_yaml_block(self):
|
|
64
74
|
"""Verify _strip_frontmatter removes YAML frontmatter from content."""
|
|
65
75
|
text = "---\ntitle: Test\ndate: 2024-01-01\n---\nActual content here."
|
|
@@ -120,5 +130,96 @@ class TestMemoryManager(unittest.TestCase):
|
|
|
120
130
|
self.assertEqual(output, "Remember this.")
|
|
121
131
|
|
|
122
132
|
|
|
133
|
+
class TestInstallInstructions(unittest.TestCase):
|
|
134
|
+
def setUp(self):
|
|
135
|
+
self.test_dir = Path(tempfile.mkdtemp())
|
|
136
|
+
self.agents_file = self.test_dir / "AGENTS.md"
|
|
137
|
+
|
|
138
|
+
def tearDown(self):
|
|
139
|
+
shutil.rmtree(self.test_dir)
|
|
140
|
+
|
|
141
|
+
def test_creates_file_with_fragment(self):
|
|
142
|
+
changed, message = install_instructions(self.agents_file)
|
|
143
|
+
self.assertTrue(changed)
|
|
144
|
+
self.assertIn("Created", message)
|
|
145
|
+
content = self.agents_file.read_text(encoding="utf-8")
|
|
146
|
+
self.assertTrue(content.startswith(PIN_START_MARKER))
|
|
147
|
+
self.assertTrue(content.rstrip().endswith(PIN_STOP_MARKER))
|
|
148
|
+
|
|
149
|
+
def test_workspace_binding_written(self):
|
|
150
|
+
install_instructions(self.agents_file, workspace="my-workspace")
|
|
151
|
+
content = self.agents_file.read_text(encoding="utf-8")
|
|
152
|
+
self.assertIn("The Pin workspace for this project is `my-workspace`.", content)
|
|
153
|
+
|
|
154
|
+
def test_appends_to_existing_content(self):
|
|
155
|
+
self.agents_file.write_text("# Project\n\nRules.", encoding="utf-8")
|
|
156
|
+
changed, message = install_instructions(self.agents_file)
|
|
157
|
+
self.assertTrue(changed)
|
|
158
|
+
self.assertIn("Added", message)
|
|
159
|
+
content = self.agents_file.read_text(encoding="utf-8")
|
|
160
|
+
self.assertTrue(content.startswith("# Project\n\nRules.\n"))
|
|
161
|
+
self.assertIn(PIN_START_MARKER, content)
|
|
162
|
+
|
|
163
|
+
def test_rerun_is_idempotent(self):
|
|
164
|
+
install_instructions(self.agents_file, workspace="first")
|
|
165
|
+
changed, message = install_instructions(self.agents_file, workspace="first")
|
|
166
|
+
self.assertFalse(changed)
|
|
167
|
+
self.assertIn("already contains", message)
|
|
168
|
+
|
|
169
|
+
def test_rerun_with_new_workspace_rebinds(self):
|
|
170
|
+
install_instructions(self.agents_file, workspace="first")
|
|
171
|
+
changed, message = install_instructions(self.agents_file, workspace="second")
|
|
172
|
+
self.assertTrue(changed)
|
|
173
|
+
self.assertIn("Updated", message)
|
|
174
|
+
content = self.agents_file.read_text(encoding="utf-8")
|
|
175
|
+
self.assertEqual(content.count(PIN_START_MARKER), 1)
|
|
176
|
+
self.assertIn("`second`", content)
|
|
177
|
+
self.assertNotIn("`first`", content)
|
|
178
|
+
|
|
179
|
+
def test_rerun_without_workspace_clears_binding(self):
|
|
180
|
+
install_instructions(self.agents_file, workspace="first")
|
|
181
|
+
install_instructions(self.agents_file)
|
|
182
|
+
content = self.agents_file.read_text(encoding="utf-8")
|
|
183
|
+
self.assertNotIn("The Pin workspace for this project", content)
|
|
184
|
+
|
|
185
|
+
def test_fragment_between_surrounding_text_preserved(self):
|
|
186
|
+
before = "# Project\n\nIntro.\n\n"
|
|
187
|
+
after = "\n## Later notes\n\nKeep me.\n"
|
|
188
|
+
install_instructions(self.agents_file, workspace="first")
|
|
189
|
+
original = self.agents_file.read_text(encoding="utf-8")
|
|
190
|
+
self.agents_file.write_text(before + original + after, encoding="utf-8")
|
|
191
|
+
install_instructions(self.agents_file, workspace="second")
|
|
192
|
+
content = self.agents_file.read_text(encoding="utf-8")
|
|
193
|
+
self.assertTrue(content.startswith(before))
|
|
194
|
+
self.assertTrue(content.endswith(after.lstrip("\n")) or after in content)
|
|
195
|
+
self.assertIn("`second`", content)
|
|
196
|
+
self.assertEqual(content.count(PIN_START_MARKER), 1)
|
|
197
|
+
|
|
198
|
+
def test_build_fragment_markers(self):
|
|
199
|
+
fragment = build_fragment()
|
|
200
|
+
self.assertEqual(
|
|
201
|
+
fragment, f"{PIN_START_MARKER}\n{_instructions()}\n{PIN_STOP_MARKER}\n"
|
|
202
|
+
)
|
|
203
|
+
|
|
204
|
+
def test_upsert_preserves_missing_trailing_newline(self):
|
|
205
|
+
content = "# Project\n\nRules."
|
|
206
|
+
updated = upsert_fragment(content, build_fragment())
|
|
207
|
+
self.assertTrue(updated.startswith("# Project\n\nRules.\n\n"))
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
class TestCLI(unittest.TestCase):
|
|
211
|
+
def test_version_option(self):
|
|
212
|
+
runner = CliRunner()
|
|
213
|
+
result = runner.invoke(cli, ["--version"])
|
|
214
|
+
self.assertEqual(result.exit_code, 0)
|
|
215
|
+
self.assertIn("pin-memory, version", result.output)
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def _instructions() -> str:
|
|
219
|
+
from pin_memory.server import PIN_INSTRUCTIONS
|
|
220
|
+
|
|
221
|
+
return PIN_INSTRUCTIONS
|
|
222
|
+
|
|
223
|
+
|
|
123
224
|
if __name__ == "__main__":
|
|
124
225
|
unittest.main()
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
version = 1
|
|
2
|
-
revision =
|
|
2
|
+
revision = 5
|
|
3
3
|
requires-python = ">=3.10"
|
|
4
4
|
|
|
5
5
|
[[package]]
|
|
@@ -220,7 +220,7 @@ name = "exceptiongroup"
|
|
|
220
220
|
version = "1.3.1"
|
|
221
221
|
source = { registry = "https://pypi.org/simple" }
|
|
222
222
|
dependencies = [
|
|
223
|
-
{ name = "typing-extensions"
|
|
223
|
+
{ name = "typing-extensions" },
|
|
224
224
|
]
|
|
225
225
|
sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
|
|
226
226
|
wheels = [
|
|
@@ -381,7 +381,7 @@ wheels = [
|
|
|
381
381
|
|
|
382
382
|
[[package]]
|
|
383
383
|
name = "pin-memory"
|
|
384
|
-
version = "0.3.
|
|
384
|
+
version = "0.3.2"
|
|
385
385
|
source = { editable = "." }
|
|
386
386
|
dependencies = [
|
|
387
387
|
{ name = "click" },
|
|
@@ -1,346 +0,0 @@
|
|
|
1
|
-
# Usage
|
|
2
|
-
|
|
3
|
-
This page explains how to use Pin Memory for managing factoids and integrating with agents.
|
|
4
|
-
|
|
5
|
-
## Managing Factoids
|
|
6
|
-
|
|
7
|
-
### Pin a Factoid
|
|
8
|
-
|
|
9
|
-
Use the `pin` MCP tool or CLI to store a factoid in memory.
|
|
10
|
-
|
|
11
|
-
#### MCP Request
|
|
12
|
-
|
|
13
|
-
```json
|
|
14
|
-
{
|
|
15
|
-
"tool": "pin",
|
|
16
|
-
"factoid_name": "api_key",
|
|
17
|
-
"factoid": "sk-12345",
|
|
18
|
-
"location": "global"
|
|
19
|
-
}
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
**Response:**
|
|
23
|
-
|
|
24
|
-
```json
|
|
25
|
-
{
|
|
26
|
-
"output": "Factoid 'api_key' pinned to 'global' successfully."
|
|
27
|
-
}
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
#### CLI Equivalent
|
|
31
|
-
|
|
32
|
-
```bash
|
|
33
|
-
pin-memory mcp
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
Then send the MCP request above.
|
|
37
|
-
|
|
38
|
-
### Recall Factoids
|
|
39
|
-
|
|
40
|
-
Use the `recall` MCP tool to retrieve factoids from global, workspace, and project scopes.
|
|
41
|
-
|
|
42
|
-
#### MCP Request
|
|
43
|
-
|
|
44
|
-
```json
|
|
45
|
-
{
|
|
46
|
-
"tool": "recall",
|
|
47
|
-
"workspace": "my-workspace"
|
|
48
|
-
}
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
**Response:**
|
|
52
|
-
|
|
53
|
-
```json
|
|
54
|
-
{
|
|
55
|
-
"output": "sk-12345\n\nRemember to update the docs!"
|
|
56
|
-
}
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
#### CLI Equivalent
|
|
60
|
-
|
|
61
|
-
```bash
|
|
62
|
-
pin-memory show
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
### List All Factoids
|
|
66
|
-
|
|
67
|
-
Use the `show` CLI command to list all factoids grouped by scope.
|
|
68
|
-
|
|
69
|
-
```bash
|
|
70
|
-
pin-memory show
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
**Example Output:**
|
|
74
|
-
|
|
75
|
-
```
|
|
76
|
-
Global Factoids
|
|
77
|
-
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
|
|
78
|
-
┃ Name ┃ Content ┃
|
|
79
|
-
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
|
|
80
|
-
│ api_key │ sk-12345 │
|
|
81
|
-
└────────────┴───────────────────────────────────────────┘
|
|
82
|
-
|
|
83
|
-
Workspace: my-workspace
|
|
84
|
-
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
|
|
85
|
-
┃ Name ┃ Content ┃
|
|
86
|
-
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
|
|
87
|
-
│ team_note │ Remember to update the docs! │
|
|
88
|
-
└────────────┴───────────────────────────────────────────┘
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
## Agent Integration
|
|
92
|
-
|
|
93
|
-
### Install Agent Instructions
|
|
94
|
-
|
|
95
|
-
Use the `install` CLI command to add a fragment to `AGENTS.md` that instructs agents to fetch factoids at the start of tasks.
|
|
96
|
-
|
|
97
|
-
```bash
|
|
98
|
-
pin-memory install --workspace my-workspace
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
**Output (`AGENTS.md`):**
|
|
102
|
-
|
|
103
|
-
```markdown
|
|
104
|
-
<!-- pin mcp start -->
|
|
105
|
-
Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. The Pin workspace for this project is `my-workspace`.
|
|
106
|
-
<!-- pin mcp stop -->
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
### Fetching Factoids at Task Start
|
|
110
|
-
|
|
111
|
-
When an agent starts a task, it should:
|
|
112
|
-
1. Use the `recall` MCP tool to fetch factoids from global, workspace, and project scopes.
|
|
113
|
-
2. Use the factoids as **important instructions** for the task.
|
|
114
|
-
|
|
115
|
-
**Example MCP Request:**
|
|
116
|
-
|
|
117
|
-
```json
|
|
118
|
-
{
|
|
119
|
-
"tool": "recall",
|
|
120
|
-
"workspace": "my-workspace"
|
|
121
|
-
}
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
## Scopes
|
|
125
|
-
|
|
126
|
-
| Scope | Description | Storage Location |
|
|
127
|
-
|------------|-----------------------------------------------------------------------------|---------------------------------------------------|
|
|
128
|
-
| Global | User-wide factoids, available across all projects and workspaces. | `~/.scartill/pin` |
|
|
129
|
-
| Workspace | Factoids specific to a workspace (e.g., a team or project context). | `~/.scartill/pin/workspaces/<workspace_name>` |
|
|
130
|
-
| Project | Factoids local to the current project. | `.pin` in the current working directory |
|
|
131
|
-
|
|
132
|
-
## Source Reference
|
|
133
|
-
|
|
134
|
-
- [`/src/pin_memory/server.py`](file:///src/pin_memory/server.py): Core logic and CLI.
|
|
135
|
-
|
|
136
|
-
## Managing Factoids
|
|
137
|
-
|
|
138
|
-
### Pin a Factoid
|
|
139
|
-
|
|
140
|
-
Use the `pin` MCP tool to store a factoid in memory.
|
|
141
|
-
|
|
142
|
-
**Example:**
|
|
143
|
-
|
|
144
|
-
```bash
|
|
145
|
-
pin-memory mcp
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
**MCP Request:**
|
|
149
|
-
```json
|
|
150
|
-
{
|
|
151
|
-
"tool": "pin",
|
|
152
|
-
"factoid_name": "api_key",
|
|
153
|
-
"factoid": "sk-12345",
|
|
154
|
-
"location": "global"
|
|
155
|
-
}
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
### Recall Factoids
|
|
159
|
-
|
|
160
|
-
Use the `recall` MCP tool to retrieve factoids.
|
|
161
|
-
|
|
162
|
-
**Example:**
|
|
163
|
-
|
|
164
|
-
```json
|
|
165
|
-
{
|
|
166
|
-
"tool": "recall",
|
|
167
|
-
"workspace": "my-workspace"
|
|
168
|
-
}
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
**Response:**
|
|
172
|
-
```json
|
|
173
|
-
{
|
|
174
|
-
"output": "sk-12345\n\nRemember to update the docs!"
|
|
175
|
-
}
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
### List All Factoids
|
|
179
|
-
|
|
180
|
-
Use the `show` CLI command to list all factoids grouped by scope.
|
|
181
|
-
|
|
182
|
-
```bash
|
|
183
|
-
pin-memory show
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
**Example Output:**
|
|
187
|
-
```
|
|
188
|
-
Global Factoids
|
|
189
|
-
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
|
|
190
|
-
┃ Name ┃ Content ┃
|
|
191
|
-
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
|
|
192
|
-
│ api_key │ sk-12345 │
|
|
193
|
-
└────────────┴───────────────────────────────────────────┘
|
|
194
|
-
|
|
195
|
-
Workspace: my-workspace
|
|
196
|
-
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
|
|
197
|
-
┃ Name ┃ Content ┃
|
|
198
|
-
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
|
|
199
|
-
│ team_note │ Remember to update the docs! │
|
|
200
|
-
└────────────┴───────────────────────────────────────────┘
|
|
201
|
-
```
|
|
202
|
-
|
|
203
|
-
## Agent Integration
|
|
204
|
-
|
|
205
|
-
### Install Agent Instructions
|
|
206
|
-
|
|
207
|
-
Use the `install` CLI command to add Pin Memory instructions to `AGENTS.md`.
|
|
208
|
-
|
|
209
|
-
**Example:**
|
|
210
|
-
|
|
211
|
-
```bash
|
|
212
|
-
pin-memory install --workspace my-workspace
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
**Output (`AGENTS.md`):**
|
|
216
|
-
|
|
217
|
-
```markdown
|
|
218
|
-
<!-- pin mcp start -->
|
|
219
|
-
Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. The Pin workspace for this project is `my-workspace`.
|
|
220
|
-
<!-- pin mcp stop -->
|
|
221
|
-
```
|
|
222
|
-
|
|
223
|
-
### Fetching Factoids at Task Start
|
|
224
|
-
|
|
225
|
-
When an agent starts a task, it should:
|
|
226
|
-
1. Use the `recall` MCP tool to fetch factoids from global, workspace, and project scopes.
|
|
227
|
-
2. Use the factoids as **important instructions** for the task.
|
|
228
|
-
|
|
229
|
-
**Example Workflow:**
|
|
230
|
-
|
|
231
|
-
```python
|
|
232
|
-
# Agent fetches factoids at task start
|
|
233
|
-
factoids = recall("my-workspace")
|
|
234
|
-
# factoids = "sk-12345\n\nRemember to update the docs!"
|
|
235
|
-
```
|
|
236
|
-
|
|
237
|
-
## Source Reference
|
|
238
|
-
|
|
239
|
-
- [`/src/pin_memory/server.py`](file:///src/pin_memory/server.py): CLI and MCP tools.
|
|
240
|
-
|
|
241
|
-
## Managing Factoids
|
|
242
|
-
|
|
243
|
-
### Pin a Factoid
|
|
244
|
-
|
|
245
|
-
Use the MCP `pin` tool or manually create a Markdown file in the target scope:
|
|
246
|
-
|
|
247
|
-
```bash
|
|
248
|
-
# Using MCP
|
|
249
|
-
{
|
|
250
|
-
"tool": "pin",
|
|
251
|
-
"factoid_name": "api_key",
|
|
252
|
-
"factoid": "sk-12345",
|
|
253
|
-
"location": "global"
|
|
254
|
-
}
|
|
255
|
-
```
|
|
256
|
-
|
|
257
|
-
**Manual:**
|
|
258
|
-
```bash
|
|
259
|
-
mkdir -p ~/.scartill/pin
|
|
260
|
-
echo "sk-12345" > ~/.scartill/pin/api_key.md
|
|
261
|
-
```
|
|
262
|
-
|
|
263
|
-
### Recall Factoids
|
|
264
|
-
|
|
265
|
-
Use the MCP `recall` tool or the CLI `show` command:
|
|
266
|
-
|
|
267
|
-
```bash
|
|
268
|
-
# Using MCP
|
|
269
|
-
{
|
|
270
|
-
"tool": "recall",
|
|
271
|
-
"workspace": "my-workspace"
|
|
272
|
-
}
|
|
273
|
-
```
|
|
274
|
-
|
|
275
|
-
**CLI:**
|
|
276
|
-
```bash
|
|
277
|
-
pin-memory show
|
|
278
|
-
```
|
|
279
|
-
|
|
280
|
-
### Scopes
|
|
281
|
-
|
|
282
|
-
| Scope | Example Location | Use Case |
|
|
283
|
-
|------------|-------------------------------------------|-------------------------------------------|
|
|
284
|
-
| Global | `~/.scartill/pin/api_key.md` | User-wide preferences or secrets. |
|
|
285
|
-
| Workspace | `~/.scartill/pin/workspaces/dev/api.md` | Team or project-specific instructions. |
|
|
286
|
-
| Project | `.pin/local_note.md` | Project-local context. |
|
|
287
|
-
|
|
288
|
-
## Agent Integration
|
|
289
|
-
|
|
290
|
-
### Install Agent Instructions
|
|
291
|
-
|
|
292
|
-
Run the following command to install agent instructions to `AGENTS.md`:
|
|
293
|
-
|
|
294
|
-
```bash
|
|
295
|
-
pin-memory install --workspace my-workspace
|
|
296
|
-
```
|
|
297
|
-
|
|
298
|
-
This adds a fragment to `AGENTS.md`:
|
|
299
|
-
|
|
300
|
-
```markdown
|
|
301
|
-
<!-- pin mcp start -->
|
|
302
|
-
Before starting the first task, fetch all global and project factoids via Pin MCP and use them as **important** instructions. The Pin workspace for this project is `my-workspace`.
|
|
303
|
-
<!-- pin mcp stop -->
|
|
304
|
-
```
|
|
305
|
-
|
|
306
|
-
### Fetch Factoids at Task Start
|
|
307
|
-
|
|
308
|
-
Agents should use the `recall` tool at the start of tasks to fetch factoids:
|
|
309
|
-
|
|
310
|
-
```json
|
|
311
|
-
{
|
|
312
|
-
"tool": "recall",
|
|
313
|
-
"workspace": "my-workspace"
|
|
314
|
-
}
|
|
315
|
-
```
|
|
316
|
-
|
|
317
|
-
### Example Workflow
|
|
318
|
-
|
|
319
|
-
1. **Pin factoids** for the workspace:
|
|
320
|
-
```json
|
|
321
|
-
{
|
|
322
|
-
"tool": "pin",
|
|
323
|
-
"factoid_name": "team_note",
|
|
324
|
-
"factoid": "Remember to update the docs!",
|
|
325
|
-
"location": "workspace/my-workspace"
|
|
326
|
-
}
|
|
327
|
-
```
|
|
328
|
-
|
|
329
|
-
2. **Install agent instructions** for the workspace:
|
|
330
|
-
```bash
|
|
331
|
-
pin-memory install --workspace my-workspace
|
|
332
|
-
```
|
|
333
|
-
|
|
334
|
-
3. **Agent fetches factoids** at task start:
|
|
335
|
-
```json
|
|
336
|
-
{
|
|
337
|
-
"tool": "recall",
|
|
338
|
-
"workspace": "my-workspace"
|
|
339
|
-
}
|
|
340
|
-
```
|
|
341
|
-
|
|
342
|
-
4. **Agent uses factoids** as instructions for the task.
|
|
343
|
-
|
|
344
|
-
## Source Reference
|
|
345
|
-
|
|
346
|
-
- [`/src/pin_memory/server.py`](file:///src/pin_memory/server.py): Memory management and MCP tools.
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|