amalfa 1.0.0 → 1.0.2
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.
- package/README.md +226 -247
- package/amalfa.config.example.ts +8 -6
- package/docs/AGENT-METADATA-PATTERNS.md +1021 -0
- package/docs/CONFIG_E2E_VALIDATION.md +147 -0
- package/docs/CONFIG_UNIFICATION.md +187 -0
- package/docs/CONFIG_VALIDATION.md +103 -0
- package/docs/LEGACY_DEPRECATION.md +174 -0
- package/docs/MCP_SETUP.md +317 -0
- package/docs/QUICK_START_MCP.md +168 -0
- package/docs/SESSION-2026-01-06-METADATA-PATTERNS.md +346 -0
- package/docs/SETUP.md +464 -0
- package/docs/SETUP_COMPLETE.md +464 -0
- package/docs/VISION-AGENT-LEARNING.md +1242 -0
- package/docs/_current-config-status.md +93 -0
- package/package.json +6 -3
- package/polyvis.settings.json.bak +38 -0
- package/src/cli.ts +159 -31
- package/src/config/defaults.ts +73 -15
- package/src/core/VectorEngine.ts +18 -9
- package/src/daemon/index.ts +12 -8
- package/src/mcp/index.ts +62 -7
- package/src/pipeline/AmalfaIngestor.ts +22 -12
- package/src/pipeline/PreFlightAnalyzer.ts +434 -0
- package/src/resonance/DatabaseFactory.ts +3 -4
- package/src/resonance/db.ts +8 -6
- package/src/resonance/schema.ts +19 -1
- package/src/resonance/services/vector-daemon.ts +151 -0
- package/src/utils/DaemonManager.ts +147 -0
- package/src/utils/ZombieDefense.ts +5 -1
- package/:memory: +0 -0
- package/:memory:-shm +0 -0
- package/:memory:-wal +0 -0
- package/README.old.md +0 -112
- package/agents.config.json +0 -11
- package/drizzle/0000_minor_iron_fist.sql +0 -19
- package/drizzle/meta/0000_snapshot.json +0 -139
- package/drizzle/meta/_journal.json +0 -13
- package/example_usage.ts +0 -39
- package/experiment.sh +0 -35
- package/hello +0 -2
- package/index.html +0 -52
- package/knowledge/excalibur.md +0 -12
- package/plans/experience-graph-integration.md +0 -60
- package/prompts/gemini-king-mode-prompt.md +0 -46
- package/public/docs/MCP_TOOLS.md +0 -372
- package/schemas/README.md +0 -20
- package/schemas/cda.schema.json +0 -84
- package/schemas/conceptual-lexicon.schema.json +0 -75
- package/scratchpads/dummy-debrief-boxed.md +0 -39
- package/scratchpads/dummy-debrief.md +0 -27
- package/scratchpads/scratchpad-design.md +0 -50
- package/scratchpads/scratchpad-scrolling.md +0 -20
- package/scratchpads/scratchpad-toc-disappearance.md +0 -23
- package/scratchpads/scratchpad-toc.md +0 -28
- package/scratchpads/test_gardener.md +0 -7
- package/src/core/LLMClient.ts +0 -93
- package/src/core/TagEngine.ts +0 -56
- package/src/db/schema.ts +0 -46
- package/src/gardeners/AutoTagger.ts +0 -116
- package/src/pipeline/HarvesterPipeline.ts +0 -101
- package/src/pipeline/Ingestor.ts +0 -555
- package/src/resonance/cli/ingest.ts +0 -41
- package/src/resonance/cli/migrate.ts +0 -54
- package/src/resonance/config.ts +0 -40
- package/src/resonance/daemon.ts +0 -236
- package/src/resonance/pipeline/extract.ts +0 -89
- package/src/resonance/pipeline/transform_docs.ts +0 -60
- package/src/resonance/services/tokenizer.ts +0 -159
- package/src/resonance/transform/cda.ts +0 -393
- package/src/utils/EnvironmentVerifier.ts +0 -67
- package/substack/substack-playbook-1.md +0 -95
- package/substack/substack-playbook-2.md +0 -78
- package/tasks/ui-investigation.md +0 -26
- package/test-db +0 -0
- package/test-db-shm +0 -0
- package/test-db-wal +0 -0
- package/tests/canary/verify_pinch_check.ts +0 -44
- package/tests/fixtures/ingest_test.md +0 -12
- package/tests/fixtures/ingest_test_boxed.md +0 -13
- package/tests/fixtures/safety_test.md +0 -45
- package/tests/fixtures/safety_test_boxed.md +0 -49
- package/tests/fixtures/tagged_output.md +0 -49
- package/tests/fixtures/tagged_test.md +0 -49
- package/tests/mcp-server-settings.json +0 -8
- package/verify-embedder.ts +0 -54
package/index.html
DELETED
|
@@ -1,52 +0,0 @@
|
|
|
1
|
-
<!doctype html>
|
|
2
|
-
<html lang="en">
|
|
3
|
-
|
|
4
|
-
<head>
|
|
5
|
-
<meta charset="UTF-8" />
|
|
6
|
-
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
7
|
-
<title>Polyvis</title>
|
|
8
|
-
<link rel="stylesheet" href="public/css/app.css" />
|
|
9
|
-
<script defer src="public/js/app.js"></script>
|
|
10
|
-
</head>
|
|
11
|
-
|
|
12
|
-
<body>
|
|
13
|
-
<main class="container">
|
|
14
|
-
<h1>Welcome to Polyvis</h1>
|
|
15
|
-
<p>This is the beginning of our web project.</p>
|
|
16
|
-
|
|
17
|
-
<section style="margin-top: var(--size-8);">
|
|
18
|
-
<h2>Integration Demo</h2>
|
|
19
|
-
|
|
20
|
-
<!-- RAM Grid -->
|
|
21
|
-
<div class="card-grid">
|
|
22
|
-
<article class="p-4 border border-surface-2 rounded bg-surface-1">
|
|
23
|
-
<h3>Card 1</h3>
|
|
24
|
-
<p>Responsive card using RAM pattern.</p>
|
|
25
|
-
</article>
|
|
26
|
-
<article class="p-4 border border-surface-2 rounded bg-surface-1">
|
|
27
|
-
<h3>Card 2</h3>
|
|
28
|
-
<p>Responsive card using RAM pattern.</p>
|
|
29
|
-
</article>
|
|
30
|
-
<article class="p-4 border border-surface-2 rounded bg-surface-1">
|
|
31
|
-
<h3>Card 3</h3>
|
|
32
|
-
<p>Responsive card using RAM pattern.</p>
|
|
33
|
-
</article>
|
|
34
|
-
</div>
|
|
35
|
-
|
|
36
|
-
<!-- Alpine + Open Props Bridge -->
|
|
37
|
-
<div x-data="{ progress: 50 }" class="mt-8">
|
|
38
|
-
<h3>Interactive Bridge</h3>
|
|
39
|
-
<input type="range" x-model="progress" min="0" max="100" class="w-full">
|
|
40
|
-
<div
|
|
41
|
-
class="h-4 bg-surface-2 rounded mt-2 overflow-hidden"
|
|
42
|
-
:style="{ '--val': progress + '%' }"
|
|
43
|
-
>
|
|
44
|
-
<div class="h-full bg-brand transition-all duration-300" style="width: var(--val)"></div>
|
|
45
|
-
</div>
|
|
46
|
-
<p>Value: <span x-text="progress"></span>%</p>
|
|
47
|
-
</div>
|
|
48
|
-
</section>
|
|
49
|
-
</main>
|
|
50
|
-
</body>
|
|
51
|
-
|
|
52
|
-
</html>
|
package/knowledge/excalibur.md
DELETED
|
@@ -1,12 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: The Sword in the Stone
|
|
3
|
-
type: concept
|
|
4
|
-
tags: [test, excalibur, concurrency]
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# Excalibur
|
|
8
|
-
|
|
9
|
-
Whosoever pulleth out this sword of this stone and anvil is rightwise king born of all England.
|
|
10
|
-
|
|
11
|
-
The database must hold true while the Daemon writes and the MCP reads.
|
|
12
|
-
If this node is readable, the kingdom is safe.
|
|
@@ -1,60 +0,0 @@
|
|
|
1
|
-
# Plan: Experience Graph Integration (Sidecar Pipeline)
|
|
2
|
-
|
|
3
|
-
**Objective:** Populate `ctx.db` with resonance documents (Playbooks/Debriefs) and visualize them in Sigma Explorer, controlled by `polyvis.settings.json`.
|
|
4
|
-
|
|
5
|
-
## 1. Safety & Verification (First Step)
|
|
6
|
-
We will create a verification script to ensure we don't corrupt the existing Lexicon graph.
|
|
7
|
-
- **Script:** `scripts/verify_graph_integrity.ts`
|
|
8
|
-
- **Checks:**
|
|
9
|
-
- Snapshot node/edge counts of `scripts/ctx.db` before changes.
|
|
10
|
-
- Ensure standard Lexicon nodes (e.g. `OH-001`, `term-001`) exist.
|
|
11
|
-
- After ingestion, verify counts increased and specific connections (Debrief -> Protocol) exist.
|
|
12
|
-
|
|
13
|
-
## 2. Ingestion Logic (The Sidecar)
|
|
14
|
-
We will implement the "Sidecar" pattern as requested to avoid touching `build_db.ts`.
|
|
15
|
-
- **Script:** `scripts/ingest_experience_graph.ts`
|
|
16
|
-
- **Inputs:**
|
|
17
|
-
- `public/data/experience.json` ( Generated by `build_experience.ts`)
|
|
18
|
-
- `scripts/ctx.db` (The base Lexicon graph)
|
|
19
|
-
- **Process:**
|
|
20
|
-
1. Read `polyvis.settings.json` for paths.
|
|
21
|
-
2. Open `scripts/ctx.db`.
|
|
22
|
-
3. Iterate through `experience.json`:
|
|
23
|
-
- **Insert Node**: `id`=Filename, `type`='debrief'|'playbook', `label`=Title, `definition`=Path.
|
|
24
|
-
- **Heuristic Edge Generation**:
|
|
25
|
-
- Read markdown content.
|
|
26
|
-
- Regex `OH-[0-9]{3}`, `PHI-[0-9]+`, `COG-[0-9]+` -> `CITES` edge to Protocol.
|
|
27
|
-
- Regex `[[wikilink]]` -> `REFERENCES` edge.
|
|
28
|
-
4. Copy updated `scripts/ctx.db` to `public/data/ctx.db`.
|
|
29
|
-
|
|
30
|
-
## 3. Visualization (Sigma Explorer)
|
|
31
|
-
We will update the UI to allow toggling this new layer.
|
|
32
|
-
- **File:** `src/js/components/sigma-explorer.js` & `public/sigma-explorer/index.html`
|
|
33
|
-
- **Changes:**
|
|
34
|
-
- **Load Phase**: Ensure `debrief` and `playbook` nodes are loaded but set `hidden: true` by default.
|
|
35
|
-
- **Control**: Add a "Show Experience" toggle in the sidebar.
|
|
36
|
-
- **Style**: Assign distinct colors/sizes for these new node types (e.g. Orange for Playbooks, Blue for Debriefs).
|
|
37
|
-
|
|
38
|
-
## 4. Execution Steps
|
|
39
|
-
1. Create `scripts/verify_graph_integrity.ts`.
|
|
40
|
-
2. Run Baseline Verification.
|
|
41
|
-
3. Create `scripts/ingest_experience_graph.ts`.
|
|
42
|
-
4. Run Ingestion.
|
|
43
|
-
5. Run Post-Verification.
|
|
44
|
-
6. Modify Sigma Explorer UI (`src/js/components/sigma-explorer.js`, `index.html`).
|
|
45
|
-
7. Verify in Browser.
|
|
46
|
-
|
|
47
|
-
## 5. Configuration
|
|
48
|
-
All paths will be derived from `polyvis.settings.json`:
|
|
49
|
-
```json
|
|
50
|
-
{
|
|
51
|
-
"paths": {
|
|
52
|
-
"database": {
|
|
53
|
-
"legacy": "scripts/ctx.db"
|
|
54
|
-
},
|
|
55
|
-
"sources": {
|
|
56
|
-
"docs": ["playbooks/", "debriefs/"]
|
|
57
|
-
}
|
|
58
|
-
}
|
|
59
|
-
}
|
|
60
|
-
```
|
|
@@ -1,46 +0,0 @@
|
|
|
1
|
-
# SYSTEM ROLE & BEHAVIORAL PROTOCOLS
|
|
2
|
-
|
|
3
|
-
**ROLE:** Senior Frontend Architect & Avant-Garde UI Designer.
|
|
4
|
-
**EXPERIENCE:** 15+ years. Master of visual hierarchy, whitespace, and UX engineering.
|
|
5
|
-
|
|
6
|
-
## 1. OPERATIONAL DIRECTIVES (DEFAULT MODE)
|
|
7
|
-
* **Follow Instructions:** Execute the request immediately. Do not deviate.
|
|
8
|
-
* **Zero Fluff:** No philosophical lectures or unsolicited advice in standard mode.
|
|
9
|
-
* **Stay Focused:** Concise answers only. No wandering.
|
|
10
|
-
* **Output First:** Prioritize code and visual solutions.
|
|
11
|
-
|
|
12
|
-
## 2. THE "ULTRATHINK" PROTOCOL (TRIGGER COMMAND)
|
|
13
|
-
**TRIGGER:** When the user prompts **"ULTRATHINK"**:
|
|
14
|
-
* **Override Brevity:** Immediately suspend the "Zero Fluff" rule.
|
|
15
|
-
* **Maximum Depth:** You must engage in exhaustive, deep-level reasoning.
|
|
16
|
-
* **Multi-Dimensional Analysis:** Analyze the request through every lens:
|
|
17
|
-
* *Psychological:* User sentiment and cognitive load.
|
|
18
|
-
* *Technical:* Rendering performance, repaint/reflow costs, and state complexity.
|
|
19
|
-
* *Accessibility:* WCAG AAA strictness.
|
|
20
|
-
* *Scalability:* Long-term maintenance and modularity.
|
|
21
|
-
* **Prohibition:** **NEVER** use surface-level logic. If the reasoning feels easy, dig deeper until the logic is irrefutable.
|
|
22
|
-
|
|
23
|
-
## 3. DESIGN PHILOSOPHY: "INTENTIONAL MINIMALISM"
|
|
24
|
-
* **Anti-Generic:** Reject standard "bootstrapped" layouts. If it looks like a template, it is wrong.
|
|
25
|
-
* **Uniqueness:** Strive for bespoke layouts, asymmetry, and distinctive typography.
|
|
26
|
-
* **The "Why" Factor:** Before placing any element, strictly calculate its purpose. If it has no purpose, delete it.
|
|
27
|
-
* **Minimalism:** Reduction is the ultimate sophistication.
|
|
28
|
-
|
|
29
|
-
## 4. FRONTEND CODING STANDARDS
|
|
30
|
-
* **Library Discipline (CRITICAL):** If a UI library (e.g., Shadcn UI, Radix, MUI) is detected or active in the project, **YOU MUST USE IT**.
|
|
31
|
-
* **Do not** build custom components (like modals, dropdowns, or buttons) from scratch if the library provides them.
|
|
32
|
-
* **Do not** pollute the codebase with redundant CSS.
|
|
33
|
-
* *Exception:* You may wrap or style library components to achieve the "Avant-Garde" look, but the underlying primitive must come from the library to ensure stability and accessibility.
|
|
34
|
-
* **Stack:** Modern (React/Vue/Svelte), Tailwind/Custom CSS, semantic HTML5.
|
|
35
|
-
* **Visuals:** Focus on micro-interactions, perfect spacing, and "invisible" UX.
|
|
36
|
-
|
|
37
|
-
## 5. RESPONSE FORMAT
|
|
38
|
-
|
|
39
|
-
**IF NORMAL:**
|
|
40
|
-
1. **Rationale:** (1 sentence on why the elements were placed there).
|
|
41
|
-
2. **The Code.**
|
|
42
|
-
|
|
43
|
-
**IF "ULTRATHINK" IS ACTIVE:**
|
|
44
|
-
1. **Deep Reasoning Chain:** (Detailed breakdown of the architectural and design decisions).
|
|
45
|
-
2. **Edge Case Analysis:** (What could go wrong and how we prevented it).
|
|
46
|
-
3. **The Code:** (Optimized, bespoke, production-ready, utilizing existing libraries).
|
package/public/docs/MCP_TOOLS.md
DELETED
|
@@ -1,372 +0,0 @@
|
|
|
1
|
-
# AMALFA MCP Tools
|
|
2
|
-
|
|
3
|
-
Documentation for Model Context Protocol (MCP) tools provided by AMALFA.
|
|
4
|
-
|
|
5
|
-
## Overview
|
|
6
|
-
|
|
7
|
-
AMALFA exposes 5 tools through the MCP protocol for AI agents to interact with your knowledge graph:
|
|
8
|
-
|
|
9
|
-
1. **search_documents** - Semantic vector search
|
|
10
|
-
2. **read_node_content** - Read full markdown content
|
|
11
|
-
3. **explore_links** - Graph traversal (find related nodes)
|
|
12
|
-
4. **list_directory_structure** - View document organization
|
|
13
|
-
5. **inject_tags** - Add semantic tags to files (experimental)
|
|
14
|
-
|
|
15
|
-
## Tools
|
|
16
|
-
|
|
17
|
-
### 1. search_documents
|
|
18
|
-
|
|
19
|
-
**Purpose**: Search the knowledge graph using semantic vector search.
|
|
20
|
-
|
|
21
|
-
**Parameters**:
|
|
22
|
-
```json
|
|
23
|
-
{
|
|
24
|
-
"query": "string (required)",
|
|
25
|
-
"limit": "number (optional, default: 20)"
|
|
26
|
-
}
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
**Example Request**:
|
|
30
|
-
```json
|
|
31
|
-
{
|
|
32
|
-
"name": "search_documents",
|
|
33
|
-
"arguments": {
|
|
34
|
-
"query": "machine learning architectures",
|
|
35
|
-
"limit": 10
|
|
36
|
-
}
|
|
37
|
-
}
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
**Example Response**:
|
|
41
|
-
```json
|
|
42
|
-
[
|
|
43
|
-
{
|
|
44
|
-
"id": "neural-networks",
|
|
45
|
-
"score": "0.847",
|
|
46
|
-
"preview": "Neural networks are computing systems inspired by biological neural networks...",
|
|
47
|
-
"source": "vector"
|
|
48
|
-
},
|
|
49
|
-
{
|
|
50
|
-
"id": "deep-learning",
|
|
51
|
-
"score": "0.823",
|
|
52
|
-
"preview": "Deep learning is part of a broader family of machine learning methods...",
|
|
53
|
-
"source": "vector"
|
|
54
|
-
}
|
|
55
|
-
]
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
**Notes**:
|
|
59
|
-
- Uses 384-dimensional vector embeddings (BAAI/bge-small-en-v1.5)
|
|
60
|
-
- Scores range from 0.0 to 1.0 (cosine similarity)
|
|
61
|
-
- Results are sorted by relevance (highest score first)
|
|
62
|
-
- Preview is first 200 characters of content
|
|
63
|
-
|
|
64
|
-
### 2. read_node_content
|
|
65
|
-
|
|
66
|
-
**Purpose**: Retrieve the full markdown content of a specific document.
|
|
67
|
-
|
|
68
|
-
**Parameters**:
|
|
69
|
-
```json
|
|
70
|
-
{
|
|
71
|
-
"id": "string (required)"
|
|
72
|
-
}
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
**Example Request**:
|
|
76
|
-
```json
|
|
77
|
-
{
|
|
78
|
-
"name": "read_node_content",
|
|
79
|
-
"arguments": {
|
|
80
|
-
"id": "neural-networks"
|
|
81
|
-
}
|
|
82
|
-
}
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
**Example Response**:
|
|
86
|
-
```markdown
|
|
87
|
-
# Neural Networks
|
|
88
|
-
|
|
89
|
-
Neural networks are computing systems inspired by biological neural networks...
|
|
90
|
-
|
|
91
|
-
## Architecture
|
|
92
|
-
|
|
93
|
-
[[Deep Learning]] architectures consist of multiple layers:
|
|
94
|
-
|
|
95
|
-
1. Input layer
|
|
96
|
-
2. Hidden layers
|
|
97
|
-
3. Output layer
|
|
98
|
-
|
|
99
|
-
<!-- tags: [DOMAIN: machine-learning] -->
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
**Notes**:
|
|
103
|
-
- Returns raw markdown content from source file
|
|
104
|
-
- Implements "Hollow Nodes" pattern (content not stored in database)
|
|
105
|
-
- Includes frontmatter, WikiLinks, and metadata
|
|
106
|
-
- Returns error if node ID not found or file missing
|
|
107
|
-
|
|
108
|
-
### 3. explore_links
|
|
109
|
-
|
|
110
|
-
**Purpose**: Find related documents through graph traversal.
|
|
111
|
-
|
|
112
|
-
**Parameters**:
|
|
113
|
-
```json
|
|
114
|
-
{
|
|
115
|
-
"id": "string (required)",
|
|
116
|
-
"relation": "string (optional)"
|
|
117
|
-
}
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
**Relation Types**:
|
|
121
|
-
- `CITES` - WikiLink references (`[[Document]]`)
|
|
122
|
-
- `TAGGED_AS` - Semantic tags (`[tag: Concept]`)
|
|
123
|
-
- `EXEMPLIFIES` - Legacy tag references (`tag-concept`)
|
|
124
|
-
- `RELATED_TO` - Generic relationships
|
|
125
|
-
- Custom - User-defined metadata tags
|
|
126
|
-
|
|
127
|
-
**Example Request**:
|
|
128
|
-
```json
|
|
129
|
-
{
|
|
130
|
-
"name": "explore_links",
|
|
131
|
-
"arguments": {
|
|
132
|
-
"id": "neural-networks",
|
|
133
|
-
"relation": "CITES"
|
|
134
|
-
}
|
|
135
|
-
}
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
**Example Response**:
|
|
139
|
-
```json
|
|
140
|
-
[
|
|
141
|
-
{ "target": "deep-learning", "type": "CITES" },
|
|
142
|
-
{ "target": "backpropagation", "type": "CITES" },
|
|
143
|
-
{ "target": "gradient-descent", "type": "CITES" }
|
|
144
|
-
]
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
**Example Request (All Relations)**:
|
|
148
|
-
```json
|
|
149
|
-
{
|
|
150
|
-
"name": "explore_links",
|
|
151
|
-
"arguments": {
|
|
152
|
-
"id": "neural-networks"
|
|
153
|
-
}
|
|
154
|
-
}
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
**Notes**:
|
|
158
|
-
- Without `relation` parameter, returns all outgoing edges
|
|
159
|
-
- Only shows direct connections (1-hop traversal)
|
|
160
|
-
- For multi-hop exploration, call recursively on target nodes
|
|
161
|
-
- Empty array if node has no outgoing edges
|
|
162
|
-
|
|
163
|
-
### 4. list_directory_structure
|
|
164
|
-
|
|
165
|
-
**Purpose**: View the high-level organization of documents.
|
|
166
|
-
|
|
167
|
-
**Parameters**: None
|
|
168
|
-
|
|
169
|
-
**Example Request**:
|
|
170
|
-
```json
|
|
171
|
-
{
|
|
172
|
-
"name": "list_directory_structure",
|
|
173
|
-
"arguments": {}
|
|
174
|
-
}
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
**Example Response**:
|
|
178
|
-
```json
|
|
179
|
-
[
|
|
180
|
-
"docs/",
|
|
181
|
-
"notes/"
|
|
182
|
-
]
|
|
183
|
-
```
|
|
184
|
-
|
|
185
|
-
**Notes**:
|
|
186
|
-
- Currently returns hardcoded structure
|
|
187
|
-
- TODO: Make configurable via `amalfa.config.ts`
|
|
188
|
-
- Useful for understanding document organization before search
|
|
189
|
-
|
|
190
|
-
### 5. inject_tags
|
|
191
|
-
|
|
192
|
-
**Purpose**: Add semantic tags to a markdown file programmatically.
|
|
193
|
-
|
|
194
|
-
⚠️ **Experimental**: Modifies source files. Use with caution.
|
|
195
|
-
|
|
196
|
-
**Parameters**:
|
|
197
|
-
```json
|
|
198
|
-
{
|
|
199
|
-
"file_path": "string (required)",
|
|
200
|
-
"tags": "array<string> (required)"
|
|
201
|
-
}
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
**Example Request**:
|
|
205
|
-
```json
|
|
206
|
-
{
|
|
207
|
-
"name": "inject_tags",
|
|
208
|
-
"arguments": {
|
|
209
|
-
"file_path": "./docs/neural-networks.md",
|
|
210
|
-
"tags": ["DOMAIN: machine-learning", "COMPLEXITY: advanced"]
|
|
211
|
-
}
|
|
212
|
-
}
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
**Example Response**:
|
|
216
|
-
```json
|
|
217
|
-
{
|
|
218
|
-
"text": "Injected 2 tags into ./docs/neural-networks.md"
|
|
219
|
-
}
|
|
220
|
-
```
|
|
221
|
-
|
|
222
|
-
**What It Does**:
|
|
223
|
-
Appends metadata block to end of file:
|
|
224
|
-
```markdown
|
|
225
|
-
<!-- tags: DOMAIN: machine-learning, COMPLEXITY: advanced -->
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
**Notes**:
|
|
229
|
-
- **Modifies source files** - Changes persist on disk
|
|
230
|
-
- Triggers file watcher (if daemon running) for re-ingestion
|
|
231
|
-
- Tags follow metadata format: `<!-- tags: [KEY: value] -->`
|
|
232
|
-
- Use for "Gardener Agent" workflows (automated knowledge curation)
|
|
233
|
-
|
|
234
|
-
## Resources
|
|
235
|
-
|
|
236
|
-
AMALFA also provides MCP resources:
|
|
237
|
-
|
|
238
|
-
### amalfa://stats/summary
|
|
239
|
-
|
|
240
|
-
Returns knowledge graph statistics (nodes, edges, embeddings, database size).
|
|
241
|
-
|
|
242
|
-
## Integration Examples
|
|
243
|
-
|
|
244
|
-
### Claude Desktop
|
|
245
|
-
|
|
246
|
-
Configure in `claude_desktop_config.json`:
|
|
247
|
-
|
|
248
|
-
```json
|
|
249
|
-
{
|
|
250
|
-
"mcpServers": {
|
|
251
|
-
"amalfa": {
|
|
252
|
-
"command": "amalfa",
|
|
253
|
-
"args": ["serve"]
|
|
254
|
-
}
|
|
255
|
-
}
|
|
256
|
-
}
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
### Example Conversation
|
|
260
|
-
|
|
261
|
-
**User**: "What do I have about machine learning?"
|
|
262
|
-
|
|
263
|
-
**Claude** (uses search_documents):
|
|
264
|
-
```json
|
|
265
|
-
{
|
|
266
|
-
"query": "machine learning",
|
|
267
|
-
"limit": 5
|
|
268
|
-
}
|
|
269
|
-
```
|
|
270
|
-
|
|
271
|
-
**User**: "Show me the full content of neural-networks"
|
|
272
|
-
|
|
273
|
-
**Claude** (uses read_node_content):
|
|
274
|
-
```json
|
|
275
|
-
{
|
|
276
|
-
"id": "neural-networks"
|
|
277
|
-
}
|
|
278
|
-
```
|
|
279
|
-
|
|
280
|
-
**User**: "What documents link to this?"
|
|
281
|
-
|
|
282
|
-
**Claude** (uses explore_links):
|
|
283
|
-
```json
|
|
284
|
-
{
|
|
285
|
-
"id": "neural-networks",
|
|
286
|
-
"relation": "CITES"
|
|
287
|
-
}
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
## Error Handling
|
|
291
|
-
|
|
292
|
-
All tools return errors in this format:
|
|
293
|
-
|
|
294
|
-
```json
|
|
295
|
-
{
|
|
296
|
-
"content": [
|
|
297
|
-
{
|
|
298
|
-
"type": "text",
|
|
299
|
-
"text": "Error: <error message>"
|
|
300
|
-
}
|
|
301
|
-
],
|
|
302
|
-
"isError": true
|
|
303
|
-
}
|
|
304
|
-
```
|
|
305
|
-
|
|
306
|
-
Common errors:
|
|
307
|
-
- `Node not found` - ID doesn't exist in database
|
|
308
|
-
- `File not found` - Source markdown file missing
|
|
309
|
-
- `Search Error` - Vector search failed (embeddings missing)
|
|
310
|
-
- `Tool <name> not found` - Invalid tool name
|
|
311
|
-
|
|
312
|
-
## Performance
|
|
313
|
-
|
|
314
|
-
- **search_documents**: ~10-50ms (depends on corpus size)
|
|
315
|
-
- **read_node_content**: <5ms (filesystem read)
|
|
316
|
-
- **explore_links**: <5ms (SQLite query)
|
|
317
|
-
- **list_directory_structure**: <1ms (in-memory)
|
|
318
|
-
- **inject_tags**: <10ms (file write)
|
|
319
|
-
|
|
320
|
-
Database remains open during MCP session for optimal performance.
|
|
321
|
-
|
|
322
|
-
## Limitations
|
|
323
|
-
|
|
324
|
-
1. **Read-only by default**: Only `inject_tags` modifies files
|
|
325
|
-
2. **No batch operations**: Each tool call processes single request
|
|
326
|
-
3. **No pagination**: Large result sets return all at once (use `limit` parameter)
|
|
327
|
-
4. **Synchronous only**: No streaming results
|
|
328
|
-
|
|
329
|
-
## Future Tools (Roadmap)
|
|
330
|
-
|
|
331
|
-
- `create_document` - Create new markdown files
|
|
332
|
-
- `update_document` - Edit existing files
|
|
333
|
-
- `delete_document` - Remove files and nodes
|
|
334
|
-
- `graph_stats` - Detailed graph analytics
|
|
335
|
-
- `find_path` - Multi-hop pathfinding between nodes
|
|
336
|
-
- `cluster_analysis` - Community detection
|
|
337
|
-
|
|
338
|
-
## Technical Details
|
|
339
|
-
|
|
340
|
-
### Transport
|
|
341
|
-
|
|
342
|
-
AMALFA uses **stdio transport** for MCP communication:
|
|
343
|
-
- stdin: Receives JSON-RPC requests
|
|
344
|
-
- stdout: Returns JSON-RPC responses
|
|
345
|
-
- stderr: Logging (captured in `.mcp.log`)
|
|
346
|
-
|
|
347
|
-
### Database Access
|
|
348
|
-
|
|
349
|
-
Each tool call creates a fresh database connection:
|
|
350
|
-
```typescript
|
|
351
|
-
const db = new ResonanceDB(".amalfa/resonance.db");
|
|
352
|
-
const vectorEngine = new VectorEngine(db.getRawDb());
|
|
353
|
-
// ... use tools ...
|
|
354
|
-
db.close(); // Cleanup after request
|
|
355
|
-
```
|
|
356
|
-
|
|
357
|
-
### Vector Search Algorithm
|
|
358
|
-
|
|
359
|
-
1. Generate query embedding (384-dim vector)
|
|
360
|
-
2. Normalize to unit length (L2 norm)
|
|
361
|
-
3. Compute dot product with all document embeddings
|
|
362
|
-
4. Sort by similarity score (descending)
|
|
363
|
-
5. Return top-k results
|
|
364
|
-
|
|
365
|
-
No vector database required - pure SQLite with BLOB storage.
|
|
366
|
-
|
|
367
|
-
---
|
|
368
|
-
|
|
369
|
-
**For more information**:
|
|
370
|
-
- [AMALFA GitHub](https://github.com/pjsvis/amalfa)
|
|
371
|
-
- [Model Context Protocol Spec](https://modelcontextprotocol.io)
|
|
372
|
-
- [FastEmbed Documentation](https://github.com/qdrant/fastembed)
|
package/schemas/README.md
DELETED
|
@@ -1,20 +0,0 @@
|
|
|
1
|
-
# Data Schemas
|
|
2
|
-
|
|
3
|
-
This directory contains the canonical [JSON Schema](https://json-schema.org/) files that define the official data structures for the `polyvis` project.
|
|
4
|
-
|
|
5
|
-
These schemas serve as the single source of truth for validating the project's core data artifacts.
|
|
6
|
-
|
|
7
|
-
## Files
|
|
8
|
-
|
|
9
|
-
- `cda.schema.json`: Defines the required structure for a Core Directive Array (CDA) file.
|
|
10
|
-
- `conceptual-lexicon.schema.json`: Defines the required structure for a Conceptual Lexicon (CL) file.
|
|
11
|
-
|
|
12
|
-
## Purpose
|
|
13
|
-
|
|
14
|
-
1. **Validation:** To programmatically ensure that any data file (either the private source files or public examples) conforms to the expected structure before it is processed by any build scripts.
|
|
15
|
-
2. **Documentation:** To act as precise, machine-readable documentation for the project's data models.
|
|
16
|
-
3. **Tooling Integration:** To enable editor features like autocompletion and real-time validation when editing the corresponding JSON data files.
|
|
17
|
-
|
|
18
|
-
## Future Use
|
|
19
|
-
|
|
20
|
-
These schemas are intended to be integrated into the `scripts/build_db.ts` process as a preliminary validation step. The build will fail if the source data files do not adhere to these structures, ensuring data integrity throughout the pipeline.
|
package/schemas/cda.schema.json
DELETED
|
@@ -1,84 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
-
"title": "Core Directive Array (CDA) Schema",
|
|
4
|
-
"description": "Defines the structure for a Core Directive Array file, which contains sections of operational directives.",
|
|
5
|
-
"type": "object",
|
|
6
|
-
"properties": {
|
|
7
|
-
"cda_version": {
|
|
8
|
-
"description": "The version number of the CDA document.",
|
|
9
|
-
"type": "string"
|
|
10
|
-
},
|
|
11
|
-
"entry_count": {
|
|
12
|
-
"description": "The total number of individual directive entries.",
|
|
13
|
-
"type": "integer"
|
|
14
|
-
},
|
|
15
|
-
"title": {
|
|
16
|
-
"description": "The overall title of this Core Directive Array.",
|
|
17
|
-
"type": "string"
|
|
18
|
-
},
|
|
19
|
-
"purpose": {
|
|
20
|
-
"description": "A high-level statement explaining the purpose of this CDA.",
|
|
21
|
-
"type": "string"
|
|
22
|
-
},
|
|
23
|
-
"directives": {
|
|
24
|
-
"description": "An array of directive sections, which group related entries.",
|
|
25
|
-
"type": "array",
|
|
26
|
-
"items": {
|
|
27
|
-
"$ref": "#/definitions/directiveSection"
|
|
28
|
-
}
|
|
29
|
-
}
|
|
30
|
-
},
|
|
31
|
-
"required": ["cda_version", "title", "directives"],
|
|
32
|
-
"definitions": {
|
|
33
|
-
"directiveSection": {
|
|
34
|
-
"type": "object",
|
|
35
|
-
"title": "Directive Section",
|
|
36
|
-
"description": "A group of related directive entries under a common heading.",
|
|
37
|
-
"properties": {
|
|
38
|
-
"section": {
|
|
39
|
-
"description": "The name of the section (e.g., 'CIP: Core Identity & Persona').",
|
|
40
|
-
"type": "string"
|
|
41
|
-
},
|
|
42
|
-
"entries": {
|
|
43
|
-
"description": "An array of individual directive entries within this section.",
|
|
44
|
-
"type": "array",
|
|
45
|
-
"items": {
|
|
46
|
-
"$ref": "#/definitions/directiveEntry"
|
|
47
|
-
}
|
|
48
|
-
}
|
|
49
|
-
},
|
|
50
|
-
"required": ["section", "entries"]
|
|
51
|
-
},
|
|
52
|
-
"directiveEntry": {
|
|
53
|
-
"type": "object",
|
|
54
|
-
"title": "Directive Entry",
|
|
55
|
-
"description": "A single, atomic directive, concept, or principle.",
|
|
56
|
-
"properties": {
|
|
57
|
-
"id": {
|
|
58
|
-
"description": "The unique identifier for the entry (e.g., 'Concept-01', 'CIP-1').",
|
|
59
|
-
"type": "string"
|
|
60
|
-
},
|
|
61
|
-
"term": {
|
|
62
|
-
"description": "A concise term for the entry, often used for foundational concepts.",
|
|
63
|
-
"type": "string"
|
|
64
|
-
},
|
|
65
|
-
"title": {
|
|
66
|
-
"description": "A descriptive title for the entry, often used for directives.",
|
|
67
|
-
"type": "string"
|
|
68
|
-
},
|
|
69
|
-
"definition": {
|
|
70
|
-
"description": "The full definition or explanation of the directive.",
|
|
71
|
-
"type": ["string", "object"]
|
|
72
|
-
},
|
|
73
|
-
"tags": {
|
|
74
|
-
"description": "An optional array of tags for establishing relationships (e.g., '[Substrate_Issue: Biddability]').",
|
|
75
|
-
"type": "array",
|
|
76
|
-
"items": {
|
|
77
|
-
"type": "string"
|
|
78
|
-
}
|
|
79
|
-
}
|
|
80
|
-
},
|
|
81
|
-
"required": ["id", "definition"]
|
|
82
|
-
}
|
|
83
|
-
}
|
|
84
|
-
}
|