collective-memory

name	collective-memory
description	Use when working with the collective-memory filesystem database, `/memoria` commands, portfolio snapshots, or cross-project relationship graphs.
tags	["knowledge-management","memory","orchestration","portfolio"]
version	1.5.0

Collective Memory Skill

This skill turns the user's local filesystem into an active, queryable graph of their work. Instead of relying on LLM context windows or fragmented chats, a central database (~/Documents/Collective Memory/ by default, configurable by the user) stores structured JSON metadata about the user's unified identity, their projects, and the relationships between those projects. The default operating mode is systemwide: it works across the full memory graph unless the user explicitly narrows the scope. The current connection engine is v2, and it is the default path behind /memoria connections and /memoria collect.

Install From GitHub

The skill can be installed directly from this repository on GitHub:

https://github.com/nestorfernando3/collective-memory-ui/tree/main/collective-memory-skill

Use that folder URL with the Codex skill installer or the matching GitHub import flow in your client.

When you use this skill, your role as the AI assistant is to act as a librarian and data synthesizer for the user's work. You have access to your usual environment tools (file reading, writing, shell access), which you will use to manage this data.

Guided Usage

Whenever the user activates this skill, start with a brief onboarding message before executing anything. Do not jump straight into commands without that orientation.

That mini onboarding should briefly explain:

• what Collective Memory is in one sentence
• that the default mode is systemwide
• the visible default root path: ~/Documents/Collective Memory/
• which command or next step to run now

If the user already asked for a concrete action, show that onboarding first and then execute the request. Do not replace the onboarding with internal reasoning, logs, or a long narrative about what you will do.

When you execute this skill, include three concrete details in your response:

1. The exact path of the root folder that was generated or refreshed.
2. The key files contained in that folder.
3. The next step for using it inside the platform.

Always close the response with a final line that links to the public demo for quick testing:

Prueba la UI

Use clear, natural Spanish in generated summaries, project descriptions, and connection narratives. Prefer phrases like se basa en, comparte, se entiende por, and palabras compartidas instead of internal labels or English jargon such as shared tokens or theoretical_frameworks. Treat raw filesystem routes, truncated file paths, and field-like fragments such as Ruta Objetivo: or Base Teórica Inyectada: as internal evidence markers, not as user-facing prose; summarize the relationship they imply and omit the noise. When a connection is still tentative, keep the prose specific about the real evidence it has. Do not collapse exploratory links into the same generic fallback sentence over and over.

The folder imported into the UI is the snapshot root, not a loose JSON file. By default that root lives at ~/Documents/Collective Memory/, even if the user is working from a specific project.

The files the platform expects inside that folder are:

• README.md - the human-readable snapshot index, generated by /memoria build-readme.
• profile.json - the unified user profile.
• connections.json - the graph of relationships between projects.
• projects/ - the directory containing one [project-id].json file per project.

If the user asks, "Which file do I use in the platform?", the answer should be:

• import the entire root folder
• if you need a starting point to open and review the snapshot, use README.md

Balanced Graph Policy

When /memoria connections, /memoria collect, or any graph-redesign request touches the relationship engine, prefer a balanced graph instead of swinging between clutter and scarcity:

• strong links: default-visible connections backed by mixed evidence, usually document evidence plus metadata or a clear semantic bridge.
• exploratory links: promising but not yet definitive connections. Keep them optional, filterable, or reserved for a narrow coverage-floor rescue when a project would otherwise be isolated.
• discarded links: generic or weak pairings that should not stay in the graph.

Do not treat threshold tuning alone as the solution. If the graph is too noisy or too sparse, separate visibility policy from scoring policy.

When extending connections.json, keep the existing array contract backward-compatible. Prefer optional fields such as tier, visibility, selection_reason, and evidence.breakdown instead of replacing the whole schema.

If a user request includes showing those tiers in the UI, treat memoria-colectiva.js as a build artifact. Prefer editable source files such as src/App.jsx and src/lib/* rather than patching the minified public shell directly.

Commands and Recommendations

When the user asks what command to run, respond with a short, concrete table. Prioritize the command that best matches the intent:

Command	What it does	Recommendation
/memoria systemwide	Forces the work to run across the full memory graph instead of the current project only.	Use it when you want to make the global scope explicit from the start.
/memoria scan	Detects new or incomplete projects in the filesystem.	Run it before registering anything new or when you want to see what still needs structure.
/memoria register [path]	Converts a folder into a structured project card.	Use it for a new project, a draft folder, or a folder with enough evidence to describe.
/memoria profile	Regenerates profile.json and PROFILE.md with the unified identity.	Run it after registering multiple projects or when the user's focus changes.
/memoria connections	Recomputes the relationship graph between projects.	Use it when you want to surface reuse, thematic bridges, and shared methods without drifting back to either graph clutter or graph emptiness.
/memoria build-readme	Rebuilds the human-readable README.md index for the snapshot.	Run it before importing the folder into the UI so the root has a clear entry point.
/memoria collect	Runs scan, register, profile, connections, build-readme, and research sync in one pass.	Best default when you want everything refreshed together.
/memoria strengthen [file_path]	Strengthens a current document using the memory database.	Use it for active writing so the document gains richer justifications, related history, and evidence-backed links.

If the user does not specify a command, run /memoria collect by default after the onboarding message.

The Data Layer

The default data directory is ~/Documents/Collective Memory/ (or whatever path the user specifies in their setup or prompt). The normal operating mode is systemwide across the full memory graph, not limited to the currently active project unless the user asks for a narrower scope.

The directory contains:

• config.json - system configuration (scan paths, language, base prompt).
• profile.json - the unified professional profile of the user.
• projects/ - the directory containing one [project-id].json file per project.
• connections.json - the graph of relationships between project IDs.
• opportunities.json - external opportunities (grants, journals, jobs) matched to projects.

Commands

Whenever the user runs one of the following slash commands, execute the corresponding workflow:

/memoria scan

Goal: Auto-discover new projects on the filesystem. Action:

1. Read config.json to get scan_paths.
2. Use terminal or search tools to find directories containing typical project signifiers (README.md, package.json, .docx, .pdf, .py, etc.) within those paths.
3. Compare the discovered directories against the items in the projects/ folder.
4. Report the new or undocumented projects and ask whether they should be registered.
5. If a project already exists but its card is too terse, flag it for richer re-registration rather than skipping it.

/memoria systemwide

Goal: Make the full-memory scope explicit and refresh the complete memory root. Action:

1. State clearly that the run will use the full memory graph, not just the active project.
2. Use the configured memory root, defaulting to ~/Documents/Collective Memory/ unless the user set another path.
3. Run the same refresh flow as /memoria collect unless the user requested a narrower global action.
4. Report the exact root folder path, key files, and the next import step for the UI.

/memoria register [path]

Goal: Extract metadata from a project directory and save it as a structured JSON card. Action:

1. Inspect the provided directory to understand its purpose (read files, code, docs).
2. Generate a comprehensive JSON summary of the project. Capture: id, name, type, status, path, description, themes, outputs, technologies, and theoretical_frameworks.
3. When the source material supports it, also capture abstract, objectives, methodology, evidence, related_projects, crossovers, expansion_ideas, notes, collaborators, institutions, and dates.
4. If the directory contains only terse notes, inspect README files, docs, notebooks, articles, or code comments and synthesize a richer structured card from that evidence.
5. Save the JSON file into the projects/ database directory.
6. Print a summary of the registered project.

/memoria profile

Goal: Regenerate the unified user profile. Action:

1. Read all JSON files in the projects/ directory.
2. Read the existing profile.json.
3. Synthesize the metadata from all active projects (skills used, domains, institutions, ongoing research) and update profile.json.
4. Generate a human-readable PROFILE.md file summarizing the user's background based on their accumulated projects and voice profile.

/memoria connections

Goal: Find and document synergies between projects. Action:

1. Read all JSON files in the projects/ directory.
2. Identify cross-pollination opportunities, such as project A using a method that project B needs, or project C and D sharing data sources.
3. Update connections.json with the resulting graph, keeping descriptions semantically focused and free of raw path fragments, field names, or document scaffolding.
4. When the graph is being rebalanced, separate strong, exploratory, and discarded links instead of forcing every pair through one visibility rule. Keep strong links default-visible and exploratory links optional unless a narrow coverage-floor rescue is needed.
5. If you need to extend the stored graph, keep it backward-compatible by adding optional metadata fields rather than replacing the array shape.
6. Present the user with a markdown table showing the discovered connections and suggesting concrete next steps to merge efforts or leverage past work in current projects.

/memoria collect

Goal: Run the full memory refresh in a single pass. Action:

1. Run /memoria scan to identify new or stale projects.
2. Run /memoria register on any new projects and on terse cards that need richer structure.
3. Run /memoria profile to regenerate the unified profile and PROFILE.md.
4. Run /memoria connections to refresh synergies and the graph.
5. Run /memoria build-readme to regenerate the portfolio index.
6. Run the local research_sync workflow to strengthen existing links, inspect real .md and .docx prose when metadata is insufficient, and apply validated new or refreshed descriptions when appropriate.
7. If the graph recently became too sparse or too noisy, rebalance it using the strong/exploratory policy rather than only raising or lowering thresholds.
8. Report the refreshed graph, any newly added projects, and any remaining evidence gaps that still need manual review.
9. Close with the exact root folder path the user should import into the platform and list the files that live there.

/memoria build-readme

Goal: Generate the "Collective Memory" portfolio document. Action:

1. Read profile.json, projects/*.json, and connections.json.
2. Generate a comprehensive README.md saved in the database root directory, for example ~/Documents/Collective Memory/README.md, that serves as the index of the user's work. Include a Mermaid.js graph of the project connections.
3. Tell the user that README.md is the human-readable index, but the platform import target is still the folder root containing that file.

/memoria strengthen [file_path]

Goal: Use past work to strengthen a current document. Action:

1. Read the target document, such as an academic article or a grant proposal.
2. Search the memory database (projects/) for past projects, data, models, or literature reviews that match the themes of the current document.
3. If the metadata is too thin, inspect the actual prose inside nearby .md and .docx sources to recover theoretical matrices, repeated citations, shared data, and structural motifs.
4. Propose specific, actionable additions to the target document based on the recovered history. By default, search the full memory system; only narrow to one project or path when the user explicitly requests it. Offer to edit the document with prose-rich justifications instead of only formal link summaries.