greplica
Persistent, searchable engineering memory for AI coding agents. Saves ~50% tokens and ~30% time while planning
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/autoloops--greplica)HTML
<a href="/listings/autoloops--greplica"><img src="/api/listings/autoloops--greplica/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Most users should not install Greplica by hand. Paste this into your coding agent from inside the repo you want Greplica to remember.
Greplica requires Node.js 22-26.
Install Greplica for this repo using https://raw.githubusercontent.com/Autoloops/greplica/refs/heads/main/docs/agent-install-prompt.md.
Full prompt: [docs/agent-install-prompt.md](https://raw.githubusercontent.com/Autoloops/greplica/refs/heads/main/docs/agent-install-prompt.md)
That prompt runs a short setup questionnaire, installs Greplica in local or managed mode, and either creates the first local context or connects to existing shared memory.
To visualize your current memory in a browser, run:
greplica graph view
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 255 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <div align="center">
- <img alt="Greplica logo" src="docs/assets/greplica-logo.png" width="420">
- ### Persistent, searchable engineering memory for AI coding agents
- <p>
- <a href="https://www.npmjs.com/package/greplica"><img alt="npm package" src="https://img.shields.io/npm/v/greplica?color=111111"></a>
- <img alt="Agents" src="https://img.shields.io/badge/agents-Codex%20%7C%20Claude%20Code-2563eb">
- <img alt="Storage" src="https://img.shields.io/badge/storage-local%20SQLite-475569">
- <img alt="Embeddings" src="https://img.shields.io/badge/embeddings-local%20%7C%20OpenAI-16a34a">
- <a href="https://discord.gg/q2R6AYXh9"><img alt="Discord" src="https://img.shields.io/badge/discord-join-5865F2"></a>
- </p>
- </div>
- ---
- Does your coding agent spend 5 minutes just grepping around when you give it a complex task?
- That's because it is re-learning context. Every new session, your agent wastes tokens and time building context on work it already did. And still misses important facts.
- **Greplica** explores your repo structure, code and session transcripts to give your agent a persistent, maintained memory it can query before exploring. Local mode stays fully local with no telemetry; managed mode connects an authorized repository to shared team memory.
- ---
- ## Agent Quick Start
- Most users should not install Greplica by hand. Paste this into your coding agent from inside the repo you want Greplica to remember.
- Greplica requires Node.js 22-26.
- ```txt
- Install Greplica for this repo using https://raw.githubusercontent.com/Autoloops/greplica/refs/heads/main/docs/agent-install-prompt.md.
- ```
- Full prompt: [docs/agent-install-prompt.md](https://raw.githubusercontent.com/Autoloops/greplica/refs/heads/main/docs/agent-install-prompt.md)
- That prompt runs a short setup questionnaire, installs Greplica in local or managed mode, and either creates the first local context or connects to existing shared memory.
- To visualize your current memory in a browser, run:
- ```bash
- greplica graph view
- ```
- ---
- ## Shared Managed Memory
- Managed mode lets contributors on different clones and forks query the same repository memory. It requires Greplica `0.2.0` or later and access to a managed Greplica server.
- After an administrator invites your GitHub user to an organization or repository, run:
- ```bash
- npm install -g greplica@latest
- cd /path/to/your/repository-or-fork
- greplica login --api-url https://memory.autoloops.ai
- greplica install --mode managed --platform codex
- greplica repo status
- greplica graph context "What should I know before changing this subsystem?"
- ```
- An organization admin can instead create one reusable, repository-scoped reader link from a folder already connected to the memory:
- ```bash
- greplica repo invite-link create
- ```
- Give the printed link or command to an agent. It logs in when needed, claims access, installs Greplica, and upgrades local memory to the invited managed memory:
- ```bash
- greplica install --invite-link <invite-url> --platform codex
- ```
- The link works for multiple GitHub users until an admin revokes it. Greplica never creates a new managed-memory namespace through this link. When ordinary managed discovery finds no access or invite, creation requires the user to type `create managed memory`; an agent must ask rather than supply that confirmation itself.
- Replace `codex` with your agent platform. Login uses GitHub's browser device flow; do not share GitHub credentials or Greplica tokens. Interactive install can accept a matching invitation and automatically map a public fork to its upstream namespace. The GitHub App therefore does not need access to each contributor fork.
- Organization admins and members inherit read access to every organization repository. Guests can read only explicitly granted repositories. A `contributor` writes proposals to their own persistent personal working scope; `memory_admin` additionally manages repository memory access. Managed graph data stays on the server, while local SQLite stores only the repository binding, role cache, hook policy, and runtime session metadata.
- Managed retrieval defaults to canonical `main` plus your own persistent working memory. Add other contributors explicitly when reviewing related work:
- ```bash
- greplica graph context "How does authentication work?" \
- --with-working alice \
- --with-working bob
- ```
- Context and generated graph views retain stable user IDs, current and historical GitHub logins, the full Git head/ref/dirty envelope, and every source origin when identical contributor drafts coalesce into one canonical object. Components, flows, and claims expose the same provenance badges and filters.
- Managed GitHub repositories reconcile Memory PRs against exact default-branch code through the official reusable workflow. Pin the reusable workflow to a full commit SHA; do not use a branch or movable tag:
- ```yaml
- name: Greplica memory
- on:
- push:
- branches: [main] # Replace with the repository's default branch.
- schedule:
- - cron: "17 * * * *"
- workflow_dispatch:
- permissions:
- contents: read
- id-token: write
- jobs:
- reconcile-memory:
- permissions:
- contents: read
- id-token: write
- uses: Autoloops/greplica/.github/workflows/reconcile.yml@<full-40-character-commit-sha>
- with:
- managed-repo: <managed-repository-uuid>
- merge-sha: ${{ github.sha }}
- ```
- The push trigger reconciles immediately after default-branch updates; the hourly schedule retries unmatched and stalled work without a human memory-admin step. The workflow checks out `merge-sha` with full history, installs an immutable Greplica Action revision, proves that each code PR's recorded merge commit is contained in that exact checkout, audits every eligible Memory PR's version-keyed claim and component anchors (including code drift from stored baselines), and attests through GitHub OIDC. It does not use a repository or model secret.
- When a compatible managed server requests repair evidence, the Action also submits a deterministic packet bound to that exact SHA. It reads only the anchors named by the selected claim and component versions—never a repository-wide content scan—and limits the packet to 128 anchors, 4 KiB and 80 lines per snippet, and 64 KiB of snippets total. Snippets can come only from regular blobs tracked at the attested commit, with the checkout bytes verified against that blob. Traversal is rejected; ignored/untracked files, symlinks, submodules, sensitive paths, binary or oversized files, and high-confidence credential content are represented only as non-content omissions. For evidence-enabled candidates, the version-keyed audit and fingerprints are derived from that same packet; omissions become explicit `unverifiable` failures rather than independently appearing clean. Managed repair may use only `resolved` or `file_only` entries whose transmitted snippet hash and current anchor fingerprint are present and valid. Older servers retain the prior attestation shape.
- Managed Greplica must allowlist both signed reusable-workflow claims for the pinned revision:
- - `job_workflow_ref=Autoloops/greplica/.github/workflows/reconcile.yml@<full-40-character-commit-sha>`
- - `job_workflow_sha=<the-same-full-40-character-commit-sha>`
- Those claims prove the trusted reusable workflow ran. A token issued directly to a consumer-authored workflow or a composite Action alone is not sufficient.
- Local mode remains independent and does not require login or a server:
- ```bash
- greplica install --mode local --platform codex --embedding local
- ```
- ---
- ## How It Works
- Your past agent sessions contain repo context: decisions people made, constraints agents found, files behind workflows, gotchas, and approaches that failed. Greplica keeps the durable parts so the next agent can start with that history.
- | Step | What happens |
- | --- | --- |
- | Past sessions | Agents uncover repo-specific decisions, constraints, workflows, and file anchors. |
- | Greplica stores it | Greplica saves the durable parts as `components`, `flows`, `claims`. |
- | New agent asks | The agent runs `greplica graph context "<question>"` before broad exploration. |
- | Agent uses it | The agent starts with facts, target files, subsystem boundaries, prior decisions. |
- | Memory updates | Hooks or `greplica-update-working-memory` save useful new learnings after work sessions. |
- If you have old sessions, `greplica-fast-session-bootstrap` can ingest bundled transcripts during setup. That gives Greplica useful memory on day one.
- For example, a future task might ask about sync auth in a browser extension. The agent can start with:
- ```bash
- greplica graph context "google sync auth startup identity browser settings"
- ```
- Greplica returns a small Markdown packet the agent can act on:
- ```markdown
- # Graph Context
- ## Best Claims
- ### claim.sync_auth_mode_startup
- The sync service checks auth mode during startup before enabling Google Drive sync.
- Anchor: `src/background/sync-service.ts`
- ### claim.edge_identity_gap
- Edge does not expose the same Google identity API behavior as Chrome.
- Anchor: `src/platform/browser-identity.ts`
- ## Related Flows
- - `flow.sync_startup`: startup settings, auth checks, and sync-service initialization.
- - `flow.browser_identity`: browser-specific identity API behavior.
- ```
- ### How this helps the agent
- At task start, the agent gets a target list: the sync service, browser identity wrapper, startup flow, and the prior constraints that matter. It reads the current code before changing anything, but it verifies the right area first.
- That saves the work agents repeat across sessions: broad `rg` searches, adjacent module reads to infer ownership, and rediscovery of decisions a previous session found. This makes your agent more reliable, and leads to it generating better plans.
- ---
- ## SWE-chat Benchmarks
- We also benchmark Greplica on held-out planning tasks built from [SWE-chat](https://www.swe-chat.com/), a dataset of real coding-agent sessions from public repositories ([dataset](https://huggingface.co/datasets/SALT-NLP/SWE-chat), [paper](https://arxiv.org/abs/2604.20779)).
- For each case, we start from a clean base snapshot of the repo and use 2-4 earlier sessions from that same repo to build Greplica context. Then we run the same held-out planning task in two modes: a baseline run with no Greplica context, and a Greplica run where the agent can query `greplica graph context` during the task. One bootstrap pass plus replayed session updates gives the agent saved repo-specific decisions and workflow knowledge.
- In several showcased planning cases, Greplica cut token usage by 40-50%. Stronger runs saved wall-clock time. Greplica improved the plan when the task depended on repo-specific constraints, decisions, and subsystem boundaries. In the strongest run we measured, Greplica used 75.0% fewer tokens and finished about 38% faster.
- Current showcase rows:
- | Case | Score | Tokens | Tokens Saved | Time Saved | Why It Helped |
- | --- | ---: | ---: | ---: | ---: | --- |
- | Gemini Voyager sync/auth hardened | `100 -> 100` | `1,925,152 -> 480,988` | `1,444,164` fewer, `75.0%` | `140.4s` | Memory surfaced sync auth, startup, browser identity, and settings constraints. |
- | IPTVnator playback layout | `64 -> 100` | `1,592,080 -> 881,541` | `710,539` fewer, `44.6%` | `65s` | Memory pointed at player, workspace, playlist, and radio layout boundaries. |
- | Marin Harbor SWE eval support | `6 -> 100` | `2,992,034 -> 2,193,023` | `799,011` fewer, `26.7%` | `80.2s` | Memory surfaced vendored Harbor, mini-swe-agent compatibility, and validation constraints. |
- ---
- ## Commands
- ```bash
- greplica install --mode local --platform codex|claude|copilot|cursor|opencode|openhands|factory-droid|antigravity --embedding local|openai [--hooks enabled|disabled] [--auto-memory enabled|disabled]
- greplica login [--api-url https://memory.autoloops.ai]
- greplica install --mode managed [--platform codex|claude|copilot|cursor|opencode|openhands|factory-droid|antigravity] [--managed-repo <uuid>] [--hooks enabled|disabled] [--auto-memory enabled|disabled]
- greplica install --invite-link <url> --platform codex|claude|copilot|cursor|opencode|openhands|factory-droid|antigravity
- greplica repo invite-link create|list
- greplica repo invite-link revoke --link <uuid>
- greplica repo invite-contributor --github-user <login>
- greplica repo grant-contributor --user <managed-user-id>
- greplica repo revoke-contributor --user <managed-user-id>
- greplica logout
- greplica whoami
- greplica repo status
- greplica config
- greplica doctor [--check-embeddings]
- greplica embeddings prewarm
- greplica graph read [--with-working <login>...] [--memory-pr <id>] [--main-only] [--include-quarantined] [--json]
- greplica graph context "<query>" [--with-working <login>...] [--memory-pr <id>] [--main-only] [--include-quarantined] [--json|--debug]
- greplica graph audit anchors
- greplica graph view [--with-working <login>...] [--memory-pr <id>] [--main-only] [--include-quarantined] [--json] [--out <file>] [--no-open]
- greplica graph export <dir>
- greplica proposal validate <proposal.json>
- greplica proposal apply <proposal.json>
- greplica proposal list|show
- greplica memory pr list|show|context|retry
- greplica memory status [--json]
- greplica session mark-memory-current --session-ref <ref>
- greplica transcript bundle --platform codex|claude|copilot|opencode --file <path> [--file <path>...] --out <bundle.md>
- ```
- - `greplica graph context "<query>"` - returns Markdown for agent use. Add `--debug` for the full retrieval payload with ranking signals.
- - `greplica graph read` - prints the current graph view: all components, flows, claims, sources, and edges in scope.
- - `greplica graph view` to visualize the current memory in a local HTML file, which opens in your default browser. Use `--out` to choose where the file is written; by default it goes to a temp path.
- - `greplica transcript bundle` - converts one or more Codex, Claude Code, GitHub Copilot CLI, or OpenCode transcripts into a sanitized Markdown bundle for `greplica-fast-session-bootstrap`.
- - `greplica embeddings prewarm` - downloads and initializes the local embedding model ahead of the first query when local embeddings are configured.
- - `greplica session mark-memory-current` - marks a tracked agent session as already reflected in working memory.
- - `greplica doctor` - verifies installation and diagnoses configuration failures. Not a required preflight before every command.
- - `greplica install` prepares repo state, local storage, and agent integration; normal repo commands require install first. Local and managed mode are selected independently per repository.
- - `greplica login` authenticates managed mode through GitHub and stores the Greplica JWT separately in `~/.greplica/credentials.json`.
- For **OpenHands**, install is repo-local: skills are written to `.agents/skills/` and the `UserPromptSubmit`/`Stop` hooks to `.openhands/hooks.json` (Claude/Codex/Copilot install to the agent's home config instead). GitHub Copilot CLI installs personal skills under `~/.copilot/skills` (or `$COPILOT_HOME/skills`) and user hooks under `~/.copilot/hooks/greplica.json`. The hooks inject `graph context` guidance and trigger background working-memory updates; OpenHands must trust the repo hooks for the background save to run.
- For **Cursor**, skills are written to `~/.cursor/skills` and the `beforeSubmitPrompt`/`stop` hooks to `~/.cursor/hooks.json` (both overridable via `$CURSOR_HOME`). `greplica-bootstrap` and `greplica graph context` guidance is delivered through an always-applied project rule at `.cursor/rules/greplica.mdc` rather than the hook, because Cursor's `beforeSubmitPrompt` hook cannot inject prompt context; the hooks track sessions and trigger `greplica-update-working-memory`. A user-authored `greplica.mdc` is never overwritten (install falls back to `greplica-N.mdc`). Reload Cursor if the new rule does not appear immediately. Background working-memory updates run the Cursor CLI (`cursor-agent`), so that must be installed and authenticated for automatic saves; session tracking and guidance work without it.
- ## License
- MIT. See [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.